@open-agent-toolkit/cli 0.2.73 → 0.2.75

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 (149) hide show
  1. package/assets/bundle-metadata.json +1 -1
  2. package/assets/docs/cli-utilities/configuration.md +3 -56
  3. package/assets/docs/cli-utilities/tool-packs.md +4 -4
  4. package/assets/docs/contributing/code.md +2 -2
  5. package/assets/docs/contributing/index.md +0 -1
  6. package/assets/docs/reference/cli-reference.md +1 -1
  7. package/assets/docs/reference/troubleshooting.md +17 -40
  8. package/assets/docs/workflows/projects/artifacts.md +16 -34
  9. package/assets/docs/workflows/projects/lifecycle.md +20 -19
  10. package/assets/docs/workflows/skills/explainer-kit.md +180 -440
  11. package/assets/docs/workflows/skills/index.md +1 -2
  12. package/assets/public-package-versions.json +4 -4
  13. package/assets/skills/explainer-kit/SKILL.md +96 -171
  14. package/assets/skills/explainer-kit/recipes/engineer-tour.json +1 -22
  15. package/assets/skills/explainer-kit/recipes/program-recap.json +1 -29
  16. package/assets/skills/explainer-kit/recipes/project-explainer.json +1 -22
  17. package/assets/skills/explainer-kit/recipes/project-recap.v2.json +1 -43
  18. package/assets/skills/explainer-kit/references/fact-base-contract.md +76 -101
  19. package/assets/skills/explainer-kit/references/recap-authoring.md +99 -0
  20. package/assets/skills/explainer-kit/schemas/manifest.schema.json +13 -135
  21. package/assets/skills/explainer-kit/scripts/bundle.mjs +712 -0
  22. package/assets/skills/explainer-kit/scripts/lib/claim-subject.mjs +40 -0
  23. package/assets/skills/explainer-kit/scripts/lib/contracts.mjs +113 -1504
  24. package/assets/skills/explainer-kit/scripts/lib/failure.mjs +13 -0
  25. package/assets/skills/explainer-kit/scripts/lib/package-coverage.mjs +57 -403
  26. package/assets/skills/explainer-kit/scripts/lib/qa-result.mjs +168 -0
  27. package/assets/skills/explainer-kit/scripts/lib/qa.mjs +90 -488
  28. package/assets/skills/explainer-kit/scripts/lib/recipes.mjs +28 -545
  29. package/assets/skills/explainer-kit/scripts/lib/run-package.mjs +120 -0
  30. package/assets/skills/explainer-kit/scripts/lib/sanitize.mjs +42 -0
  31. package/assets/skills/explainer-kit/scripts/record.mjs +335 -0
  32. package/assets/skills/explainer-kit/scripts/verify.mjs +648 -0
  33. package/assets/skills/oat-explainer-kit/SKILL.md +57 -117
  34. package/assets/skills/oat-explainer-kit/references/config-contract.md +20 -64
  35. package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md +85 -237
  36. package/assets/skills/oat-explainer-kit/scripts/bind-project-sources.mjs +18 -10
  37. package/assets/skills/oat-explainer-kit/scripts/check-core.mjs +1 -0
  38. package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs +256 -21
  39. package/assets/skills/oat-explainer-kit/scripts/persist-intent.mjs +82 -3
  40. package/assets/skills/oat-explainer-kit/scripts/resolve-config.mjs +0 -162
  41. package/assets/skills/oat-explainer-kit/scripts/resolve-intent.mjs +57 -123
  42. package/assets/skills/oat-project-autonomous/SKILL.md +14 -13
  43. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +165 -165
  44. package/assets/skills/oat-project-complete/SKILL.md +168 -349
  45. package/assets/skills/oat-project-complete/scripts/consume-persisted-recap-intent.mjs +125 -0
  46. package/assets/skills/oat-project-complete/scripts/execute-synced-archive-entry.mjs +0 -30
  47. package/assets/skills/oat-project-complete/scripts/parse-completion-retry-fields.mjs +4 -37
  48. package/assets/skills/oat-project-complete/scripts/parse-synced-archive-resume-fields.mjs +17 -16
  49. package/assets/skills/oat-project-complete/scripts/recover-completion-receipts.mjs +9 -174
  50. package/assets/skills/oat-project-complete/scripts/resolve-completion-retry.mjs +1 -2
  51. package/assets/skills/oat-project-document/SKILL.md +1 -1
  52. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +165 -165
  53. package/assets/skills/oat-project-implement/SKILL.md +1 -1
  54. package/assets/skills/oat-project-implement/references/completion-and-closeout.md +44 -56
  55. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +165 -165
  56. package/assets/skills/oat-project-lite/SKILL.md +1 -1
  57. package/assets/skills/oat-project-lite/references/docs/autonomy-contract.md +165 -165
  58. package/assets/skills/oat-project-plan/SKILL.md +5 -6
  59. package/assets/skills/oat-project-pr-final/SKILL.md +1 -1
  60. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +165 -165
  61. package/assets/skills/oat-project-quick-start/SKILL.md +1 -1
  62. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +165 -165
  63. package/assets/skills/oat-project-summary/SKILL.md +35 -25
  64. package/assets/skills/oat-wave-execute/SKILL.md +11 -36
  65. package/assets/skills/oat-wave-program/SKILL.md +13 -37
  66. package/dist/commands/config/index.d.ts.map +1 -1
  67. package/dist/commands/config/index.js +9 -113
  68. package/dist/commands/project/archive/archive-utils.d.ts.map +1 -1
  69. package/dist/commands/project/archive/archive-utils.js +32 -184
  70. package/dist/commands/project/archive/explainer-package-coverage.d.ts +3 -8
  71. package/dist/commands/project/archive/explainer-package-coverage.d.ts.map +1 -1
  72. package/dist/commands/project/archive/explainer-package-coverage.js +1 -1
  73. package/dist/config/oat-config.d.ts +0 -11
  74. package/dist/config/oat-config.d.ts.map +1 -1
  75. package/dist/config/oat-config.js +0 -34
  76. package/dist/config/resolve.d.ts.map +1 -1
  77. package/dist/config/resolve.js +0 -8
  78. package/dist/release/public-package-contract.d.ts.map +1 -1
  79. package/dist/release/public-package-contract.js +2 -10
  80. package/dist/validation/project-state.d.ts.map +1 -1
  81. package/dist/validation/project-state.js +42 -3
  82. package/package.json +2 -2
  83. package/assets/docs/contributing/explainer-kit-verification.md +0 -133
  84. package/assets/docs/workflows/skills/explainer-kit-providers.md +0 -155
  85. package/assets/skills/explainer-kit/briefs/deep-dive.md +0 -35
  86. package/assets/skills/explainer-kit/briefs/project-page.md +0 -38
  87. package/assets/skills/explainer-kit/briefs/supporting-diagram.md +0 -28
  88. package/assets/skills/explainer-kit/briefs/walkthrough-deck.md +0 -35
  89. package/assets/skills/explainer-kit/examples/project-explainer/content.md +0 -31
  90. package/assets/skills/explainer-kit/examples/project-explainer/fact-base.md +0 -22
  91. package/assets/skills/explainer-kit/examples/project-recap/content.md +0 -77
  92. package/assets/skills/explainer-kit/examples/project-recap/fact-base.json +0 -104
  93. package/assets/skills/explainer-kit/examples/project-recap/fact-base.md +0 -44
  94. package/assets/skills/explainer-kit/examples/theme-bundle.json +0 -87
  95. package/assets/skills/explainer-kit/recipes/project-recap.v1.json +0 -93
  96. package/assets/skills/explainer-kit/references/contracts.md +0 -324
  97. package/assets/skills/explainer-kit/references/destination-contract.md +0 -210
  98. package/assets/skills/explainer-kit/references/extension-contract.md +0 -80
  99. package/assets/skills/explainer-kit/references/golden-conformance.md +0 -80
  100. package/assets/skills/explainer-kit/references/visual-review.md +0 -71
  101. package/assets/skills/explainer-kit/schemas/author-request.v2.schema.json +0 -212
  102. package/assets/skills/explainer-kit/schemas/author-request.v3.schema.json +0 -241
  103. package/assets/skills/explainer-kit/schemas/author-result.v2.schema.json +0 -52
  104. package/assets/skills/explainer-kit/schemas/build-record.schema.json +0 -98
  105. package/assets/skills/explainer-kit/schemas/durability-evidence.schema.json +0 -53
  106. package/assets/skills/explainer-kit/schemas/publish-receipt.v1.schema.json +0 -97
  107. package/assets/skills/explainer-kit/schemas/publish-receipt.v2.schema.json +0 -215
  108. package/assets/skills/explainer-kit/schemas/publish-request.v1.schema.json +0 -32
  109. package/assets/skills/explainer-kit/schemas/publish-request.v2.schema.json +0 -34
  110. package/assets/skills/explainer-kit/schemas/run-request.schema.json +0 -147
  111. package/assets/skills/explainer-kit/schemas/set-plan.v1.schema.json +0 -149
  112. package/assets/skills/explainer-kit/schemas/terminal-evidence.v1.schema.json +0 -81
  113. package/assets/skills/explainer-kit/schemas/visual-review-evidence.v1.schema.json +0 -66
  114. package/assets/skills/explainer-kit/schemas/visual-review-request.v1.schema.json +0 -117
  115. package/assets/skills/explainer-kit/schemas/visual-review-result.v1.schema.json +0 -80
  116. package/assets/skills/explainer-kit/scripts/lib/catalog.mjs +0 -349
  117. package/assets/skills/explainer-kit/scripts/lib/content-approval.mjs +0 -418
  118. package/assets/skills/explainer-kit/scripts/lib/diagram.mjs +0 -514
  119. package/assets/skills/explainer-kit/scripts/lib/durability.mjs +0 -643
  120. package/assets/skills/explainer-kit/scripts/lib/fact-base.mjs +0 -664
  121. package/assets/skills/explainer-kit/scripts/lib/internal-references.mjs +0 -538
  122. package/assets/skills/explainer-kit/scripts/lib/markdown.mjs +0 -414
  123. package/assets/skills/explainer-kit/scripts/lib/publication-policy.mjs +0 -54
  124. package/assets/skills/explainer-kit/scripts/lib/records.mjs +0 -954
  125. package/assets/skills/explainer-kit/scripts/lib/render.mjs +0 -703
  126. package/assets/skills/explainer-kit/scripts/lib/s3-roots.mjs +0 -353
  127. package/assets/skills/explainer-kit/scripts/lib/s3-static.mjs +0 -759
  128. package/assets/skills/explainer-kit/scripts/lib/set-plan.mjs +0 -209
  129. package/assets/skills/explainer-kit/scripts/lib/source-backlinks.mjs +0 -218
  130. package/assets/skills/explainer-kit/scripts/lib/terminal-evidence.mjs +0 -157
  131. package/assets/skills/explainer-kit/scripts/lib/visual-review.mjs +0 -400
  132. package/assets/skills/explainer-kit/scripts/publish.mjs +0 -76
  133. package/assets/skills/explainer-kit/scripts/record-durability.mjs +0 -64
  134. package/assets/skills/explainer-kit/scripts/render-qa.mjs +0 -461
  135. package/assets/skills/explainer-kit/scripts/run.mjs +0 -3038
  136. package/assets/skills/explainer-kit/scripts/validate.mjs +0 -59
  137. package/assets/skills/oat-explainer-kit/references/author-callback.md +0 -53
  138. package/assets/skills/oat-explainer-kit/references/migration.md +0 -144
  139. package/assets/skills/oat-explainer-kit/references/visual-review-callback.md +0 -83
  140. package/assets/skills/oat-explainer-kit/scripts/derive-destination.mjs +0 -91
  141. package/assets/skills/oat-explainer-kit/scripts/finalize-tracked-run.mjs +0 -531
  142. package/assets/skills/oat-explainer-kit/scripts/probe-recap-seams.mjs +0 -371
  143. package/assets/skills/oat-explainer-kit/scripts/run.mjs +0 -905
  144. package/dist/commands/project/archive/explainer-source-backlinks.d.ts +0 -18
  145. package/dist/commands/project/archive/explainer-source-backlinks.d.ts.map +0 -1
  146. package/dist/commands/project/archive/explainer-source-backlinks.js +0 -27
  147. package/dist/commands/project/archive/explainer-terminal-evidence.d.ts +0 -29
  148. package/dist/commands/project/archive/explainer-terminal-evidence.d.ts.map +0 -1
  149. package/dist/commands/project/archive/explainer-terminal-evidence.js +0 -37
@@ -7,8 +7,15 @@ const EXPLAINER_SOURCES = [
7
7
  'interactive',
8
8
  'kickoff_prompt',
9
9
  'autonomous_policy',
10
+ 'capability_probe',
11
+ 'failed_attempt',
12
+ ];
13
+ const EXPLAINER_DECISION_KEYS = [
14
+ 'decision',
15
+ 'source',
16
+ 'decided_at',
17
+ 'failed_attempt_evidence',
10
18
  ];
11
- const EXPLAINER_DECISION_KEYS = ['decision', 'source', 'decided_at'];
12
19
  const EXPLAINER_ALLOWED_PAIRS = {
13
20
  oat_project_explainer: new Set([
14
21
  'generate:interactive',
@@ -19,6 +26,8 @@ const EXPLAINER_ALLOWED_PAIRS = {
19
26
  'generate:interactive',
20
27
  'skip:interactive',
21
28
  'generate:autonomous_policy',
29
+ 'skip:capability_probe',
30
+ 'skip:failed_attempt',
22
31
  ]),
23
32
  };
24
33
  const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
@@ -60,13 +69,15 @@ function readExplainerDecision(frontmatter, key, errors) {
60
69
  if (keys.some((entry) => !EXPLAINER_DECISION_KEYS.includes(entry))) {
61
70
  errors.push({
62
71
  code: 'invalid-explainer-decision-keys',
63
- message: `${key} must contain only decision, source, and decided_at`,
72
+ message: `${key} contains an unsupported decision field`,
64
73
  });
65
74
  return null;
66
75
  }
67
76
  const decision = record.decision;
68
77
  const source = record.source;
69
78
  const decidedAt = record.decided_at;
79
+ const hasFailedAttemptEvidence = Object.hasOwn(record, 'failed_attempt_evidence');
80
+ const failedAttemptEvidence = record.failed_attempt_evidence;
70
81
  let valid = true;
71
82
  if (typeof decision !== 'string' ||
72
83
  !EXPLAINER_DECISIONS.includes(decision)) {
@@ -80,7 +91,7 @@ function readExplainerDecision(frontmatter, key, errors) {
80
91
  !EXPLAINER_SOURCES.includes(source)) {
81
92
  errors.push({
82
93
  code: 'invalid-explainer-source',
83
- message: `${key}.source must be interactive, kickoff_prompt, or autonomous_policy`,
94
+ message: `${key}.source must be interactive, kickoff_prompt, autonomous_policy, capability_probe, or failed_attempt`,
84
95
  });
85
96
  valid = false;
86
97
  }
@@ -101,14 +112,42 @@ function readExplainerDecision(frontmatter, key, errors) {
101
112
  });
102
113
  valid = false;
103
114
  }
115
+ const isFailedAttempt = key === 'oat_project_recap' &&
116
+ decision === 'skip' &&
117
+ source === 'failed_attempt';
118
+ if ((isFailedAttempt &&
119
+ !isFailedAttemptEvidenceLocator(failedAttemptEvidence)) ||
120
+ (!isFailedAttempt && hasFailedAttemptEvidence)) {
121
+ errors.push({
122
+ code: 'invalid-failed-attempt-evidence',
123
+ message: `${key}.failed_attempt_evidence is required only for skip/failed_attempt and must name explainers/<run-slug>/manifest.json or failure.json`,
124
+ });
125
+ valid = false;
126
+ }
104
127
  return valid
105
128
  ? {
106
129
  decision: decision,
107
130
  source: source,
108
131
  decided_at: decidedAt,
132
+ ...(isFailedAttempt && {
133
+ failed_attempt_evidence: failedAttemptEvidence,
134
+ }),
109
135
  }
110
136
  : null;
111
137
  }
138
+ function isFailedAttemptEvidenceLocator(value) {
139
+ if (typeof value !== 'string')
140
+ return false;
141
+ const parts = value.split('/');
142
+ const runSlug = parts[1];
143
+ const fileName = parts[2];
144
+ return (parts.length === 3 &&
145
+ parts[0] === 'explainers' &&
146
+ typeof runSlug === 'string' &&
147
+ /^[a-z0-9][a-z0-9._-]*$/.test(runSlug) &&
148
+ typeof fileName === 'string' &&
149
+ ['manifest.json', 'failure.json'].includes(fileName));
150
+ }
112
151
  function readKind(frontmatter) {
113
152
  const rawKind = readStringField(frontmatter, 'oat_kind');
114
153
  return rawKind && isProjectStateKind(rawKind) ? rawKind : 'implementation';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@open-agent-toolkit/cli",
3
- "version": "0.2.73",
3
+ "version": "0.2.75",
4
4
  "private": false,
5
5
  "description": "Open Agent Toolkit CLI",
6
6
  "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
34
34
  "ora": "^9.0.0",
35
35
  "yaml": "2.8.2",
36
36
  "zod": "^3.25.76",
37
- "@open-agent-toolkit/control-plane": "0.2.73"
37
+ "@open-agent-toolkit/control-plane": "0.2.75"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/node": "^22.10.0",
@@ -1,133 +0,0 @@
1
- ---
2
- title: Verifying Explainer Kit
3
- description: 'Maintainer runbook for semantic golden cases, temporary real-Chromium evidence, and release validation.'
4
- ---
5
-
6
- # Verifying Explainer Kit
7
-
8
- Explainer Kit uses portable behavioral goldens and a real-browser release gate.
9
- The goal is not pixel identity: output may change markup, spacing, and
10
- composition when it preserves the same meaning, topology, interactions, and
11
- evidence quality.
12
-
13
- ## Golden cases
14
-
15
- The suite under
16
- `.agents/skills/explainer-kit/tests/fixtures/golden/` contains three
17
- portable semantic cases:
18
-
19
- | Case | What it proves |
20
- | ------------------------------ | ---------------------------------------------------------- |
21
- | `simple` | Viewport-sized lead evidence and a cohesive baseline recap |
22
- | `non-linear` | Exact branch, fan-in, and cycle preservation |
23
- | `explainer-authoring-redesign` | Archive-only rebuild from a dense completed project record |
24
-
25
- Every case retains only its descriptor, source input, and content-addressed
26
- source record. The three cases share one rubric. Generated artifacts, browser
27
- evidence, screenshots, manifests, catalogs, and review results stay in a
28
- temporary test directory and are never committed. Paths are
29
- repository-relative; machine roots, home-relative paths, `file://` URLs,
30
- Windows drive paths, and UNC paths are rejected.
31
-
32
- ## Prerequisites
33
-
34
- - Install workspace dependencies.
35
- - Ensure the repository-supported Chromium runtime is installed and launchable.
36
- - Run from the repository root.
37
-
38
- The end-to-end benchmarks require an actual launched Chromium session. A
39
- deterministic fixture session is valid only for bounded unit/integration tests
40
- and cannot satisfy a golden production path.
41
-
42
- ## Run the golden suite
43
-
44
- ```bash
45
- node --test \
46
- .agents/skills/explainer-kit/tests/golden-conformance.test.mjs
47
- ```
48
-
49
- A passing run proves:
50
-
51
- - one planner-owned hub, architecture view, and deck;
52
- - source and terminology cohesion;
53
- - exact topology and catalog parity;
54
- - mobile, tablet, and desktop Chromium evidence;
55
- - one independent critic invocation; and
56
- - a passing terminal review without correction.
57
-
58
- The focused integration suites below separately exercise the one-correction
59
- ceiling.
60
-
61
- The suite recomputes semantic-input hashes, grounds every claim in retained
62
- source evidence, and evaluates the shared rubric against live runtime output.
63
- A prose claim or status label without runtime proof does not pass.
64
-
65
- The existing three-case, 27-capture golden suite is intentionally unchanged by
66
- the prose-led visual-review work. Simplifying it is a separate follow-up: first
67
- audit each case's unique coverage, runtime cost, and flakiness, then remove or
68
- replace fixtures only with evidence that the same behavior remains protected.
69
-
70
- ## Inspect generated evidence
71
-
72
- The suite materializes each case's runtime package under its temporary working
73
- directory, validates it, and removes it at test completion. Add a local
74
- debugger breakpoint or temporarily disable cleanup when diagnosing a failure;
75
- do not add generated runtime output to the fixture directories.
76
-
77
- ## Focused integrity suites
78
-
79
- Use these when changing browser identity, immutable evidence, resume, or archive
80
- contracts:
81
-
82
- ```bash
83
- node --test \
84
- .agents/skills/explainer-kit/tests/records.test.mjs \
85
- .agents/skills/explainer-kit/tests/run.integration.test.mjs
86
-
87
- node --test \
88
- .agents/skills/explainer-kit/tests/browser-runtime.test.mjs \
89
- .agents/skills/explainer-kit/tests/qa.test.mjs \
90
- .agents/skills/explainer-kit/tests/contracts.test.mjs \
91
- .agents/skills/explainer-kit/tests/durability.test.mjs \
92
- .agents/skills/explainer-kit/tests/rebuildability.test.mjs
93
-
94
- pnpm --filter @open-agent-toolkit/cli exec vitest run \
95
- src/commands/project/archive/archive-utils.test.ts \
96
- src/release/public-package-contract.test.ts
97
-
98
- node --test tools/smoke/explainer-kit/*.test.mjs
99
- ```
100
-
101
- ## Release gate
102
-
103
- The required publishable-package gate is:
104
-
105
- ```bash
106
- pnpm release:validate
107
- ```
108
-
109
- It validates all five lockstep public package tarballs and then runs the bounded
110
- curated-style/template matrix in real Chromium. The visual gate retains 65
111
- machine-readable viewport, clipping, motion, keyboard, no-JavaScript, and print
112
- measurements. Missing Chromium or untrusted retained evidence fails closed.
113
-
114
- For the full repository closeout, also run the standard checks documented in
115
- the root `AGENTS.md`:
116
-
117
- ```bash
118
- pnpm check
119
- pnpm type-check
120
- pnpm test
121
- pnpm build
122
- pnpm run check:skill-bumps
123
- pnpm release:check-versions
124
- pnpm release:validate
125
- pnpm build:docs
126
- pnpm lint
127
- pnpm format
128
- git diff --check
129
- ```
130
-
131
- Do not treat an isolated transient timeout as a product pass or failure without
132
- reproducing the failing test. Preserve the exact-head successful rerun evidence
133
- used for release closure.
@@ -1,155 +0,0 @@
1
- ---
2
- title: Explainer Provider Integration
3
- description: 'Provider-neutral planner, author, browser-session, and visual-critic contracts for Explainer Kit integrators.'
4
- ---
5
-
6
- # Explainer Provider Integration
7
-
8
- Explainer Kit keeps model and browser providers outside its retained request
9
- contracts. Integrators supply executable seams in process or through validated
10
- module exports; the core owns schemas, evidence binding, and terminal outcomes.
11
-
12
- For recipes, authoring behavior, themes, and lifecycle policy, start with
13
- [Explainer Kit](explainer-kit.md).
14
-
15
- ## Provider boundaries
16
-
17
- Use exactly one form for each required role:
18
-
19
- | Role | Direct input | Module-path input | Required export |
20
- | ------------------ | ---------------- | -------------------------- | ----------------------------------- |
21
- | Set planning | `planSet` | `planSetModulePath` | `planSet` function |
22
- | Artifact authoring | `author` | `authorModulePath` | `author` function |
23
- | Browser evidence | `browserSession` | `browserSessionModulePath` | branded `browserSession` descriptor |
24
- | Whole-set review | `visualCritic` | `visualCriticModulePath` | `visualCritic` function |
25
-
26
- `project-recap` requires all four roles. Other recipes require the author and
27
- use their recipe-specific planning behavior. Direct-plus-module conflicts,
28
- missing files, and invalid exports fail at the adapter boundary before core
29
- execution.
30
-
31
- Do not place browser or visual-review providers in `coreOptions`. Executable
32
- callbacks, descriptors, and module paths are transient and never enter
33
- `ExplainerRunRequestV1`, `run-request.json`, or immutable package hashes.
34
-
35
- ## Set planner
36
-
37
- The provider-neutral `planSet` callback runs once after fact reconciliation and
38
- before any author callback. It returns the complete portfolio and one shared
39
- claim ledger.
40
-
41
- For a new project recap, the portfolio must contain the required navigational
42
- hub. A diagram, deck, or deep dive is optional and must use a recipe-licensed
43
- profile, remain inside recipe and per-profile limits, and answer a distinct
44
- reader question with source evidence and a medium rationale. Version 1 recap
45
- plans remain readable for replay with their historical three-artifact floor.
46
- Duplicate identities, undeclared sources, conflicting shared terms, and
47
- unjustified optionals fail validation.
48
-
49
- Every author request receives the immutable set context and its matching planned
50
- artifact. Authors cannot add, remove, replace, or rename portfolio entries.
51
-
52
- ## Artifact author
53
-
54
- The core invokes `author` once per planned artifact with
55
- `explainer-kit.author-request/v3`. Version 2 requests remain readable for
56
- replay. The current request contains:
57
-
58
- - artifact identity, type, and authoring path;
59
- - the versioned brief and bundled medium-specific guidance;
60
- - reconciled facts and the shared set context;
61
- - the matching planned artifact;
62
- - the resolved theme; and
63
- - the bundled shell for artistic HTML; and
64
- - canonical artifact links ending in explicit `index.html` paths.
65
-
66
- Return `explainer-kit.author-result/v2` with exactly one of
67
- `content.markdown` or `content.html` and non-secret provenance. The core
68
- validates source overlap, path ownership, script identity, and structural
69
- contracts after the callback returns.
70
-
71
- The author, fact critic, browser probe, and visual critic must have distinct
72
- callback identities. One provider implementation may back multiple roles, but
73
- the adapter still requires separate executable boundaries.
74
-
75
- ## Trusted browser session
76
-
77
- Create a direct session with the compatible core:
78
-
79
- ```js
80
- const browserSession = await core.createBrowserProbeSession();
81
-
82
- try {
83
- await runOatExplainer(request, {
84
- planSet,
85
- author,
86
- browserSession,
87
- visualCritic,
88
- });
89
- } finally {
90
- await browserSession.close();
91
- }
92
- ```
93
-
94
- The factory launches Chromium and derives the runtime name and version from the
95
- actual browser instance. A private in-memory brand prevents a plain object with
96
- caller-authored `{name, version}` metadata from impersonating a trusted
97
- session. Module providers export the already branded descriptor as
98
- `browserSession`, not a bare callback.
99
-
100
- For unattended project recaps, the core chooses 320, 768, and 1440 widths and
101
- requires default-scenario PNGs. It validates the PNG signature, decoded
102
- dimensions, and pixel payload, then writes paired
103
- `explainer-kit.browser-evidence/v2` metrics. Every record retains:
104
-
105
- - launched Chromium name and version;
106
- - fixed capture settings;
107
- - one derived capture identity;
108
- - viewport and scenario;
109
- - screenshot path and byte binding; and
110
- - measured overflow, clipping, readability, motion, keyboard, deck, and theme
111
- behavior.
112
-
113
- All records in one review chain must carry the same runtime and capture
114
- identity. Deterministic fixture sessions are explicit test helpers and are
115
- rejected by unattended production recap paths.
116
-
117
- ## Whole-set visual critic
118
-
119
- The `visualCritic` receives one
120
- `explainer-kit.visual-review-request/v1` plus a confined evidence reader. The
121
- request binds:
122
-
123
- - every rendered artifact and its exact content hash;
124
- - every viewport-matched screenshot and metrics hash;
125
- - cohesion observations from the shared ledger; and
126
- - the trusted browser runtime and capture identity.
127
-
128
- Return `explainer-kit.visual-review-result/v1` with the exact request identity,
129
- all reviewed artifact IDs, structured findings, and one disposition:
130
-
131
- - `pass` completes the review gate;
132
- - `correct` requests one bounded correction and one final review; or
133
- - `fail` terminates the gate.
134
-
135
- Judge typography, hierarchy, composition, density, medium leverage, template
136
- repetition, diagram semantics, and cross-artifact cohesion from the bound
137
- browser evidence. `pass` means no required correction remains. `correct`
138
- findings name concrete artifact-scoped actions that can be completed in the
139
- single bounded correction round. Keep this judgment in prose; do not invent
140
- numeric scores or geometry thresholds.
141
-
142
- The critic must not mutate rendered files or evidence. The core revalidates all
143
- bound bytes after each callback.
144
-
145
- ## Terminal behavior
146
-
147
- There is never a second correction or third review. Missing, malformed, forged,
148
- stale, cross-record-mismatched, or mutated evidence; a thrown callback; a
149
- `fail`; or an unresolved correction produces `built-needs-review`.
150
-
151
- That outcome retains available artifacts and review evidence for diagnosis, but
152
- invokes neither durability nor publication. It cannot be finalized, archived,
153
- attested, or pushed as a successful recap.
154
-
155
- See [Troubleshooting](../../reference/troubleshooting.md) for recovery steps.
@@ -1,35 +0,0 @@
1
- # Deep-dive author brief
2
-
3
- ## Audience
4
-
5
- Write for a technical reader who already understands the parent project recap
6
- and needs enough detail to evaluate or work on one subsystem.
7
-
8
- ## Voice
9
-
10
- Be precise without becoming encyclopedic. Start with the question this page
11
- answers and the boundary it covers. Use evidence tables, code or data examples,
12
- and diagrams where they reduce explanation time. Define assumptions and call
13
- out unresolved behavior.
14
-
15
- ## Section intent
16
-
17
- Structure the page around:
18
-
19
- 1. the subsystem's purpose and boundary;
20
- 2. its inputs, outputs, and dependencies;
21
- 3. the important execution or data flow;
22
- 4. the decisions and trade-offs that shaped it;
23
- 5. failure modes, operational concerns, and validation evidence.
24
-
25
- ## Floor
26
-
27
- Produce a self-contained Markdown explainer that adds information not already
28
- present in the parent hub. Include at least one structured evidence block and
29
- link claims back to durable sources when available.
30
-
31
- ## Expansion license
32
-
33
- Depth is licensed, repetition is not. Add inline diagrams, examples, tables,
34
- and callouts when they make a difficult mechanism easier to verify. Keep
35
- adjacent topics in the parent hub or a separate justified artifact.
@@ -1,38 +0,0 @@
1
- # Program project-page author brief
2
-
3
- ## Audience
4
-
5
- Write for a program reader who followed a link from the program recap and now
6
- needs the evidence and decisions for one project.
7
-
8
- ## Voice
9
-
10
- Keep program terminology and statuses consistent with the parent hub. Be
11
- specific about this project's scope, dependencies, and outcome. Avoid
12
- repeating program-wide context unless it changes how this project should be
13
- understood.
14
-
15
- ## Section intent
16
-
17
- Cover:
18
-
19
- - the project's objective and place in the program;
20
- - delivered scope and current status;
21
- - architecture or dependency details unique to this project;
22
- - load-bearing decisions and their consequences;
23
- - validation evidence and known limits;
24
- - remaining work, owner or owning group, and next action.
25
-
26
- ## Floor
27
-
28
- Produce a self-contained Markdown explainer with a clear route back to the
29
- program story. Include at least one structured table for delivery or
30
- validation evidence and enough source references for a reader to verify the
31
- status.
32
-
33
- ## Expansion license
34
-
35
- Use inline diagrams, callouts, and evidence blocks when this project's
36
- substance warrants them. Stay within the single-project boundary. If a detail
37
- applies across the program, improve the parent recap instead of duplicating it
38
- here.
@@ -1,28 +0,0 @@
1
- # Supporting diagram author brief
2
-
3
- ## Audience
4
-
5
- Create a visual for a reader who understands the parent explainer but needs one
6
- boundary, flow, dependency, or state transition made unmistakable.
7
-
8
- ## Voice and visual intent
9
-
10
- Lead with the visual. Use short labels, consistent terminology, and a clear
11
- reading direction. Make the title state the question the diagram answers.
12
- Include a concise legend or annotation only when the visual vocabulary is not
13
- self-evident.
14
-
15
- ## Floor
16
-
17
- Compose a complete, accessible HTML diagram from the supplied
18
- `diagram-shell`. Preserve its required anchors, theme tokens, and core scripts.
19
- The diagram must have an explicit title, meaningful labels, a visible primary
20
- flow, and a short text explanation that remains useful to screen-reader users.
21
- Do not encode essential meaning through color alone.
22
-
23
- ## Expansion license
24
-
25
- Elaborate the shell's non-script markup and SVG freely when needed for
26
- legibility. Keep the scope to one coherent question. If the visual needs
27
- several unrelated panels or long prose to make sense, recommend a deep-dive
28
- instead.
@@ -1,35 +0,0 @@
1
- # Walkthrough deck author brief
2
-
3
- ## Audience
4
-
5
- Build for a live or self-guided walkthrough with teammates who need the project
6
- story in a deliberate sequence rather than a reference document.
7
-
8
- ## Voice and sequence
9
-
10
- Use one claim per slide and a clear narrative arc: context, change, system,
11
- evidence, outcome, next action. Keep text brief enough to scan at presentation
12
- distance. Use diagrams, comparisons, and evidence excerpts instead of
13
- shrinking prose to fit.
14
-
15
- ## Floor
16
-
17
- Compose a complete HTML deck from the supplied `deck-shell`. Preserve required
18
- anchors, theme tokens, keyboard navigation, progress behavior, print behavior,
19
- and all core scripts exactly. Include:
20
-
21
- - an opening frame that states the project and reader promise;
22
- - a before/after or request/outcome frame;
23
- - a high-level architecture or execution-flow visual;
24
- - a decision or trade-off frame;
25
- - a validation-evidence frame;
26
- - a closing frame with outcome and next actions.
27
-
28
- Every slide must have a useful heading, readable contrast, and a sensible
29
- no-JavaScript and print order.
30
-
31
- ## Shell-composition license
32
-
33
- The shell supplies safety and presentation mechanics. You may recompose and
34
- extend non-script markup and styling to fit the story. Do not add scripts,
35
- external active content, or inline event handlers.
@@ -1,31 +0,0 @@
1
- # Signal Relay project explainer
2
-
3
- ## Planned architecture
4
-
5
- Signed events enter through a narrow HTTP boundary. The service validates each
6
- envelope before placing it on a durable queue; workers own downstream delivery
7
- and isolate exhausted retries in a review queue.
8
-
9
- ## Decisions
10
-
11
- - Keep ingestion stateless so instances can scale independently.
12
- - Persist accepted events before acknowledging them.
13
- - Use bounded retries and a separate review queue instead of retrying forever.
14
-
15
- ## Risks
16
-
17
- The primary risk is an incompatible producer envelope. Contract tests and a
18
- shadow-ingestion period detect that drift before cutover.
19
-
20
- ## Phases
21
-
22
- 1. Validate contracts against fixtures.
23
- 2. Run shadow ingestion without downstream delivery.
24
- 3. Enable canary delivery and compare outcomes.
25
- 4. Move remaining traffic after recovery drills pass.
26
-
27
- ## Validation approach
28
-
29
- The release gate combines contract tests, duplicate-delivery tests, queue
30
- recovery drills, and operator sign-off. Supporting evidence is linked from
31
- [the example validation plan](https://docs.example.com/signal-relay/validation).
@@ -1,22 +0,0 @@
1
- # Example fact base: Signal Relay
2
-
3
- This fictional example demonstrates a pre-implementation project explainer. All
4
- organizations, systems, and links are illustrative.
5
-
6
- ## Reconciled claims
7
-
8
- - **F-001 — Planned architecture:** The relay accepts signed events, validates
9
- their envelopes, and writes accepted events to a durable queue.
10
- Source: [architecture proposal](https://docs.example.com/signal-relay/architecture).
11
- - **F-002 — Delivery:** Workers retry transient delivery failures with bounded
12
- backoff and move exhausted events to a review queue.
13
- Source: [delivery design](https://docs.example.com/signal-relay/delivery).
14
- - **F-003 — Validation:** Contract, retry, and recovery tests must pass before
15
- traffic can move from the existing path.
16
- Source: [validation plan](https://docs.example.com/signal-relay/validation).
17
-
18
- ## Reconciliation notes
19
-
20
- The proposal gives the queue ownership to the platform team while an older
21
- meeting note assigns it to the application team. The proposal is newer, so
22
- F-001 follows it and records the older assignment as superseded.
@@ -1,77 +0,0 @@
1
- # Atlas Index project recap
2
-
3
- ## Original request
4
-
5
- Every correction to the fictional Atlas Index corpus had to wait for the next
6
- overnight window, and the cost of that window grew with the corpus. The team was
7
- asked to make indexing continuous without asking a single caller to change how
8
- they query.
9
-
10
- > [!IMPORTANT]
11
- > The query contract was frozen for the whole engagement. Any option that would
12
- > have reshaped a response was out of scope before it was evaluated.
13
-
14
- ## Key agent decisions
15
-
16
- | Decision | Alternative weighed | Why it won |
17
- | ---------------------------- | ---------------------------- | -------------------------------------------------- |
18
- | Checkpoint each partition | A single global checkpoint | Replay after a crash stays inside one partition |
19
- | Make writes idempotent first | Deduplicate in each consumer | Retry safety belongs to the writer, not the reader |
20
- | Keep the rebuild as recovery | Delete it after cutover | A proven fallback costs almost nothing to retain |
21
-
22
- Each row records what was chosen and what it was chosen over, so a later reader
23
- can reconstruct the reasoning rather than just the result.
24
-
25
- ## As-built architecture
26
-
27
- ```diagram
28
- graph TD
29
- reader[Change reader] --> queue(Batch queue)
30
- queue --> worker[Index worker]
31
- worker --> index[Search index]
32
- audit{Drift beyond threshold} -->|yes| recovery[Recovery task]
33
- index --> audit
34
- ```
35
-
36
- The reader resumes from whichever checkpoint its partition last committed, so a
37
- restart repeats at most one batch. Workers apply batches by key, which makes a
38
- repeated batch indistinguishable from a first delivery. The audit closes the
39
- loop by sampling both sides on a schedule and opening a recovery task only when
40
- the difference clears the accepted threshold.
41
-
42
- ## Implementation record
43
-
44
- ```timeline
45
- 2026-02-03 — Checkpoint persistence landed behind a flag
46
- 2026-02-17 — Replay-safe workers replaced the batch writer
47
- 2026-03-02 — Drift audit and the recovery runbook shipped
48
- ```
49
-
50
- - The first milestone changed only bookkeeping, so it could ship dark.
51
- - The second made retries safe, which is what unlocked automatic recovery.
52
- - The third added the observability the operators asked for before cutover.
53
-
54
- ## Validation evidence
55
-
56
- | Suite | Scope | Result |
57
- | ------------------ | ------------------------------------------- | --------- |
58
- | Contract | Query responses across the fixture corpus | Unchanged |
59
- | Restart | Interruption at every checkpoint boundary | No gaps |
60
- | Duplicate delivery | The same batch applied twice | No drift |
61
- | Parity sampling | Scheduled samples against the source record | In budget |
62
-
63
- The full logs sit in the fictional
64
- [evidence index](https://docs.example.com/atlas-index/evidence).
65
-
66
- > [!NOTE]
67
- > How long audit samples should be retained is still an open governance
68
- > question, and it is tracked outside this recap.
69
-
70
- ## Outcome
71
-
72
- Corrections now reach readers in minutes instead of waiting for a nightly
73
- window, and the operational surface got smaller rather than larger.
74
-
75
- 1. Continuous indexing is the normal path.
76
- 2. The rebuild remains documented, exercised, and unused.
77
- 3. Drift is a monitored quantity rather than an assumption.