@t275005746/gse 0.1.0 → 0.1.2

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 (228) hide show
  1. package/.github/ISSUE_TEMPLATE/bug_report.yml +42 -42
  2. package/.github/ISSUE_TEMPLATE/change_request.yml +50 -50
  3. package/.github/ISSUE_TEMPLATE/config.yml +5 -5
  4. package/.github/PULL_REQUEST_TEMPLATE.md +38 -38
  5. package/.github/workflows/validate-gse.yml +33 -33
  6. package/.gse/README.md +18 -18
  7. package/.gse/gse-development-protocol.md +50 -50
  8. package/.gse/project-profile.md +29 -29
  9. package/.gse/quality-gates.md +25 -25
  10. package/.gse/releases/public-registry-publication-npm.md +49 -0
  11. package/.gse/releases/public-release-owner-required.md +65 -65
  12. package/.gse/releases/public-security-contact-owner-required.md +45 -45
  13. package/.gse/state.json +147 -27
  14. package/CHANGELOG.md +31 -15
  15. package/CONTRIBUTING.md +64 -64
  16. package/LICENSE +21 -21
  17. package/README.md +14 -7
  18. package/README.zh-CN.md +14 -7
  19. package/SECURITY.md +41 -41
  20. package/SKILL.md +32 -12
  21. package/SUPPORT.md +38 -38
  22. package/assets/marketplace/README.md +7 -7
  23. package/assets/marketplace/gse-listing.json +75 -75
  24. package/assets/templates/acceptance-execution-packet.md +73 -73
  25. package/assets/templates/adr.md +14 -14
  26. package/assets/templates/change-brief.md +16 -16
  27. package/assets/templates/design.md +18 -18
  28. package/assets/templates/dispatch-packet.md +100 -92
  29. package/assets/templates/evidence.md +15 -9
  30. package/assets/templates/execution-quality-pack.md +65 -65
  31. package/assets/templates/goal-map.md +21 -21
  32. package/assets/templates/host-adapter.md +48 -48
  33. package/assets/templates/host-ui-invocation-record.md +42 -42
  34. package/assets/templates/incident-review.md +60 -60
  35. package/assets/templates/public-channel-publication-record.md +49 -49
  36. package/assets/templates/public-ci-run-record.md +53 -53
  37. package/assets/templates/public-release-record.md +65 -65
  38. package/assets/templates/public-repository-settings-record.md +59 -59
  39. package/assets/templates/public-security-contact-record.md +45 -45
  40. package/assets/templates/release-trust-record.md +32 -32
  41. package/assets/templates/review.md +18 -18
  42. package/assets/templates/role-fallback-packet.md +49 -0
  43. package/assets/templates/spec.md +16 -16
  44. package/assets/templates/target-adoption-evidence.md +29 -29
  45. package/assets/templates/tasks.md +17 -17
  46. package/assets/templates/update-release-acceptance-record.md +58 -58
  47. package/examples/README.md +22 -22
  48. package/examples/agent-runtime-host/.claude/gse-adapter.md +6 -6
  49. package/examples/agent-runtime-host/.codex/gse-adapter.md +7 -7
  50. package/examples/agent-runtime-host/.gse/goal-map.md +7 -7
  51. package/examples/agent-runtime-host/.gse/project-profile.md +27 -27
  52. package/examples/agent-runtime-host/.gse/tooling.md +5 -5
  53. package/examples/agent-runtime-host/.mcp.json +9 -9
  54. package/examples/agent-runtime-host/AGENTS.md +5 -5
  55. package/examples/agent-runtime-host/README.md +10 -10
  56. package/examples/agent-runtime-host/docs/model-routing.md +5 -5
  57. package/examples/cli-tool/.gse/project-profile.md +21 -21
  58. package/examples/cli-tool/AGENTS.md +5 -5
  59. package/examples/cli-tool/README.md +12 -12
  60. package/examples/cli-tool/package.json +21 -21
  61. package/examples/small-app/.env.example +2 -2
  62. package/examples/small-app/.github/workflows/ci.yml +8 -8
  63. package/examples/small-app/AGENTS.md +5 -5
  64. package/examples/small-app/README.md +12 -12
  65. package/examples/small-app/package.json +26 -26
  66. package/examples/small-app/playwright.config.ts +4 -4
  67. package/package.json +52 -44
  68. package/references/adoption-recipes.md +171 -171
  69. package/references/agent-roles.md +42 -21
  70. package/references/architecture-health.md +101 -101
  71. package/references/benchmark-audit.md +73 -73
  72. package/references/commands.md +74 -45
  73. package/references/community-channels.md +46 -46
  74. package/references/compatibility.md +70 -70
  75. package/references/design-basis.md +38 -38
  76. package/references/domain-model.md +129 -129
  77. package/references/domain-quality-gates.md +75 -75
  78. package/references/drift-audit.md +81 -80
  79. package/references/evidence-taxonomy.md +145 -108
  80. package/references/file-ownership.md +97 -93
  81. package/references/final-form-roadmap.md +201 -0
  82. package/references/final-readiness.md +84 -84
  83. package/references/forward-test.md +133 -133
  84. package/references/goal-map.md +36 -36
  85. package/references/host-adapters.md +129 -101
  86. package/references/learning-system.md +42 -26
  87. package/references/maintenance-cadence.md +51 -0
  88. package/references/marketplace-discovery.md +46 -46
  89. package/references/model-routing.md +103 -103
  90. package/references/open-source-defaults.md +39 -39
  91. package/references/operating-model.md +52 -52
  92. package/references/packaging.md +277 -277
  93. package/references/project-agent-workspace.md +89 -89
  94. package/references/project-bootstrap.md +122 -122
  95. package/references/project-guards.md +52 -0
  96. package/references/project-profile.md +57 -57
  97. package/references/public-release.md +174 -174
  98. package/references/quality-gates.md +96 -89
  99. package/references/recovery.md +176 -176
  100. package/references/release-trust.md +43 -43
  101. package/references/release.md +126 -126
  102. package/references/review.md +141 -141
  103. package/references/role-dispatch-fallback.md +54 -0
  104. package/references/router.md +90 -90
  105. package/references/spec-workflow.md +66 -66
  106. package/references/task-levels.md +81 -81
  107. package/references/tool-adapters.md +80 -70
  108. package/scripts/audit-acceptance-execution-packet.mjs +133 -133
  109. package/scripts/audit-adoption-recipes.mjs +99 -99
  110. package/scripts/audit-change-lifecycle.mjs +77 -77
  111. package/scripts/audit-change-system.mjs +134 -134
  112. package/scripts/audit-ci-readiness.mjs +107 -107
  113. package/scripts/audit-close-gate-hardening.mjs +188 -0
  114. package/scripts/audit-close-gate.mjs +448 -262
  115. package/scripts/audit-command-adapters.mjs +91 -91
  116. package/scripts/audit-command-execution.mjs +212 -199
  117. package/scripts/audit-commands.mjs +7 -5
  118. package/scripts/audit-compatibility.mjs +149 -149
  119. package/scripts/audit-completion-plan-drill.mjs +230 -0
  120. package/scripts/audit-completion-readiness.mjs +290 -287
  121. package/scripts/audit-continue-preflight.mjs +234 -0
  122. package/scripts/audit-distribution.mjs +251 -251
  123. package/scripts/audit-domain-quality-gates.mjs +108 -108
  124. package/scripts/audit-evidence-levels.mjs +217 -0
  125. package/scripts/audit-evidence-placeholders.mjs +126 -126
  126. package/scripts/audit-evidence-review-queue.mjs +206 -0
  127. package/scripts/audit-final-acceptance-packet.mjs +9 -9
  128. package/scripts/audit-final-form-progress-report.mjs +19 -18
  129. package/scripts/audit-final-form-roadmap.mjs +157 -0
  130. package/scripts/audit-final-form-stale-copy.mjs +2 -2
  131. package/scripts/audit-final-readiness-promotion.mjs +255 -255
  132. package/scripts/audit-final-readiness.mjs +226 -226
  133. package/scripts/audit-fixtures.mjs +154 -154
  134. package/scripts/audit-fresh-session-readiness.mjs +177 -177
  135. package/scripts/audit-host-capabilities.mjs +237 -0
  136. package/scripts/audit-host-runtime-evidence-handoff.mjs +159 -159
  137. package/scripts/audit-host-runtime-invocation-drill.mjs +240 -240
  138. package/scripts/audit-host-runtime-invocations.mjs +254 -254
  139. package/scripts/audit-host-ui-invocation.mjs +132 -132
  140. package/scripts/audit-installed-sync.mjs +203 -0
  141. package/scripts/audit-learning-drift.mjs +292 -0
  142. package/scripts/audit-learning-promotion.mjs +351 -0
  143. package/scripts/audit-learning-system.mjs +24 -14
  144. package/scripts/audit-local-final-form-completion.mjs +11 -10
  145. package/scripts/audit-maintenance-cadence.mjs +139 -0
  146. package/scripts/audit-maintenance-snapshot.mjs +181 -0
  147. package/scripts/audit-marketplace-discovery.mjs +122 -122
  148. package/scripts/audit-npm-package-metadata.mjs +160 -154
  149. package/scripts/audit-npm-publish-dry-run.mjs +194 -166
  150. package/scripts/audit-npm-tarball-install.mjs +195 -189
  151. package/scripts/audit-open-source-defaults.mjs +92 -92
  152. package/scripts/audit-open-source-readiness.mjs +97 -97
  153. package/scripts/audit-owner-external-gate-kit.mjs +12 -11
  154. package/scripts/audit-project-guards.mjs +189 -0
  155. package/scripts/audit-project.mjs +144 -141
  156. package/scripts/audit-public-acceptance-command-dry-run-drill.mjs +203 -203
  157. package/scripts/audit-public-acceptance-handoff.mjs +10 -10
  158. package/scripts/audit-public-acceptance-readiness.mjs +222 -222
  159. package/scripts/audit-public-channel-publication.mjs +248 -248
  160. package/scripts/audit-public-ci-run.mjs +184 -184
  161. package/scripts/audit-public-collaboration-templates.mjs +98 -98
  162. package/scripts/audit-public-external-gate-probe.mjs +206 -206
  163. package/scripts/audit-public-release-checklist.mjs +17 -15
  164. package/scripts/audit-public-release-decision.mjs +201 -201
  165. package/scripts/audit-public-release-metadata.mjs +176 -176
  166. package/scripts/audit-public-repository-settings.mjs +237 -237
  167. package/scripts/audit-public-security-contact.mjs +171 -171
  168. package/scripts/audit-readme-docs.mjs +6 -4
  169. package/scripts/audit-recovery-readiness.mjs +98 -98
  170. package/scripts/audit-release-bundle.mjs +13 -11
  171. package/scripts/audit-release-owner-action-plan-drill.mjs +5 -4
  172. package/scripts/audit-release-owner-action-plan.mjs +10 -10
  173. package/scripts/audit-release-readiness.mjs +106 -106
  174. package/scripts/audit-release-status-manifest.mjs +4 -4
  175. package/scripts/audit-release-trust.mjs +62 -62
  176. package/scripts/audit-remote-distribution.mjs +266 -266
  177. package/scripts/audit-roadmap-consistency.mjs +234 -230
  178. package/scripts/audit-role-dispatch-fallback.mjs +212 -0
  179. package/scripts/audit-session-sync.mjs +127 -0
  180. package/scripts/audit-signing.mjs +147 -147
  181. package/scripts/audit-state-freshness.mjs +20 -14
  182. package/scripts/audit-state-repair.mjs +360 -0
  183. package/scripts/audit-target-adoption-evidence.mjs +117 -117
  184. package/scripts/audit-target-hardening-drills.mjs +267 -0
  185. package/scripts/audit-target-project.mjs +507 -507
  186. package/scripts/audit-tool-fallback-policy.mjs +180 -0
  187. package/scripts/audit-ui-browser-evidence-policy.mjs +191 -0
  188. package/scripts/audit-update-release-acceptance.mjs +136 -136
  189. package/scripts/audit-v1-target-validation.mjs +269 -269
  190. package/scripts/audit-validation-profiles.mjs +125 -123
  191. package/scripts/backfill-evidence-levels.mjs +98 -0
  192. package/scripts/check-encoding.mjs +72 -0
  193. package/scripts/close-change.mjs +116 -116
  194. package/scripts/discover-project-profile.mjs +307 -307
  195. package/scripts/generate-command-adapter.mjs +231 -231
  196. package/scripts/generate-continue-packet.mjs +1214 -0
  197. package/scripts/generate-final-acceptance-packet.mjs +188 -173
  198. package/scripts/generate-final-form-progress-report.mjs +191 -189
  199. package/scripts/generate-host-runtime-evidence-handoff.mjs +198 -191
  200. package/scripts/generate-maintenance-snapshot.mjs +216 -0
  201. package/scripts/generate-owner-external-gate-kit.mjs +295 -295
  202. package/scripts/generate-public-acceptance-handoff.mjs +168 -156
  203. package/scripts/generate-public-release-checklist.mjs +207 -207
  204. package/scripts/generate-release-bundle.mjs +505 -505
  205. package/scripts/generate-release-owner-action-plan.mjs +172 -171
  206. package/scripts/generate-release-status-manifest.mjs +199 -198
  207. package/scripts/generate-session-prompt.mjs +188 -188
  208. package/scripts/gse.mjs +67 -67
  209. package/scripts/init-change.mjs +265 -265
  210. package/scripts/init-project.mjs +793 -712
  211. package/scripts/install-gse.mjs +234 -234
  212. package/scripts/lib/evidence-placeholders.mjs +28 -28
  213. package/scripts/package-gse.mjs +174 -174
  214. package/scripts/probe-public-external-gates.mjs +167 -167
  215. package/scripts/record-host-invocation.mjs +151 -151
  216. package/scripts/record-learning.mjs +37 -8
  217. package/scripts/record-public-channel-publication.mjs +178 -178
  218. package/scripts/record-public-ci-run.mjs +180 -180
  219. package/scripts/record-public-release.mjs +175 -175
  220. package/scripts/record-public-repository-settings.mjs +209 -209
  221. package/scripts/record-public-security-contact.mjs +157 -157
  222. package/scripts/record-session-sync.mjs +87 -0
  223. package/scripts/run-gse-command.mjs +79 -47
  224. package/scripts/run-validation-profile.mjs +24 -5
  225. package/scripts/sign-gse-package.mjs +83 -83
  226. package/scripts/update-project-state.mjs +223 -223
  227. package/scripts/validate-gse.mjs +216 -0
  228. package/scripts/verify-gse-package.mjs +85 -85
@@ -48,11 +48,12 @@ const doctor = parseJson(doctorRun.stdout)
48
48
  const pendingAreas = (doctor?.pendingGates ?? []).map((gate) => gate.area).sort()
49
49
  const stateSearch = [
50
50
  state?.currentSlice?.id,
51
- state?.currentSlice?.outcome,
52
- state?.currentSlice?.status,
53
- state?.currentSlice?.nextAction,
54
- ...(state?.residualRisks ?? []),
55
- ].join('\n')
51
+ state?.currentSlice?.outcome,
52
+ state?.currentSlice?.status,
53
+ state?.currentSlice?.nextAction,
54
+ ...(state?.nextChecks ?? []),
55
+ ...(state?.residualRisks ?? []),
56
+ ].join('\n')
56
57
 
57
58
  const staleResolvedGatePhrases = [
58
59
  'authorize GitHub workflow scope',
@@ -73,20 +74,25 @@ const mentionsAllPending = pendingAreas.every((area) => stateSearch.includes(are
73
74
  ) || (
74
75
  area === 'Native slash command' && stateSearch.includes('Native slash-command')
75
76
  ))
77
+ const registryPending = pendingAreas.includes('Public registry publication')
78
+ const registryStateMatches = registryPending
79
+ ? state?.currentSlice?.status === 'blocked-external-auth' &&
80
+ (stateSearch.includes('npm is not logged in') || stateSearch.includes('not yet published on npm'))
81
+ : !stateSearch.includes('not yet published on npm') &&
82
+ !stateSearch.includes('npm is not logged in') &&
83
+ !stateSearch.includes('Publish @t275005746/gse to npm with an authorized token')
76
84
 
77
85
  const checks = [
78
86
  check('STF01', 'state JSON exists and parses', Boolean(state), '.gse/state.json'),
79
87
  check('STF02', 'public acceptance doctor runs before state freshness check', doctorRun.status === 0 && doctor?.summary?.status === 'passed', doctorRun.command),
80
- check('STF03', 'state next action mentions every current pending final-form gate', mentionsAllPending && pendingAreas.length === 2, pendingAreas.join(', ')),
88
+ check('STF03', 'state next action mentions every current pending final-form gate', mentionsAllPending, pendingAreas.join(', ')),
81
89
  check('STF04', 'state no longer routes users to resolved public CI/security/repository/marketplace gates', staleMatches.length === 0, staleMatches.length ? staleMatches.join('; ') : '.gse/state.json'),
82
- check(
83
- 'STF05',
84
- 'state marks current registry work as externally blocked by npm auth/publication',
85
- state?.currentSlice?.id === 'GSE-108-public-registry-publication' &&
86
- state?.currentSlice?.status === 'blocked-external-auth' &&
87
- (stateSearch.includes('npm is not logged in') || stateSearch.includes('not yet published on npm')),
88
- '.gse/state.json',
89
- ),
90
+ check(
91
+ 'STF05',
92
+ 'state matches current registry publication gate status',
93
+ registryStateMatches,
94
+ '.gse/state.json',
95
+ ),
90
96
  check('STF06', 'state points users to current doctor as source of truth', stateSearch.includes('/gse doctor') || stateSearch.includes('audit-public-acceptance-readiness.mjs'), '.gse/state.json'),
91
97
  ]
92
98
 
@@ -0,0 +1,360 @@
1
+ #!/usr/bin/env node
2
+ import fs from 'node:fs'
3
+ import os from 'node:os'
4
+ import path from 'node:path'
5
+ import { fileURLToPath } from 'node:url'
6
+
7
+ const args = process.argv.slice(2)
8
+
9
+ function readArg(name, fallback = null) {
10
+ const index = args.indexOf(name)
11
+ if (index === -1) return fallback
12
+ return args[index + 1] ?? fallback
13
+ }
14
+
15
+ const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
16
+ const targetArg = readArg('--target')
17
+ const jsonOnly = args.includes('--json')
18
+ const write = args.includes('--write') || args.includes('--execute')
19
+ const selfTest = args.includes('--self-test') || !targetArg
20
+ const maxActiveRisks = Number(readArg('--max-active-risks', '6'))
21
+ const maxRiskLength = Number(readArg('--max-risk-length', '260'))
22
+
23
+ function readText(filePath) {
24
+ return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '') : ''
25
+ }
26
+
27
+ function readJson(filePath) {
28
+ if (!fs.existsSync(filePath)) return { exists: false, ok: false, data: null, error: 'missing' }
29
+ try {
30
+ return { exists: true, ok: true, data: JSON.parse(readText(filePath)), error: '' }
31
+ } catch (error) {
32
+ return { exists: true, ok: false, data: null, error: error.message }
33
+ }
34
+ }
35
+
36
+ function readJsonl(filePath) {
37
+ if (!fs.existsSync(filePath)) return { exists: false, ok: false, records: [], error: 'missing', lines: [] }
38
+ const lines = readText(filePath)
39
+ .split(/\r?\n/)
40
+ .map((line) => line.trim())
41
+ .filter(Boolean)
42
+ const records = []
43
+ for (const [index, line] of lines.entries()) {
44
+ try {
45
+ records.push(JSON.parse(line))
46
+ } catch (error) {
47
+ return { exists: true, ok: false, records, error: `line ${index + 1}: ${error.message}`, lines }
48
+ }
49
+ }
50
+ return { exists: true, ok: true, records, error: '', lines }
51
+ }
52
+
53
+ function backupFile(filePath) {
54
+ if (!fs.existsSync(filePath)) return null
55
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-')
56
+ const backupDir = path.join(path.dirname(filePath), 'backups')
57
+ fs.mkdirSync(backupDir, { recursive: true })
58
+ const backupPath = path.join(backupDir, `${stamp}-${path.basename(filePath)}.bak`)
59
+ fs.copyFileSync(filePath, backupPath)
60
+ return backupPath
61
+ }
62
+
63
+ function relative(target, fullPath) {
64
+ return path.relative(target, fullPath).replace(/\\/g, '/')
65
+ }
66
+
67
+ function repairAction(id, severity, targetPath, problem, command, options = {}) {
68
+ return {
69
+ id,
70
+ severity,
71
+ targetPath,
72
+ problem,
73
+ command,
74
+ writeSupported: Boolean(options.writeSupported),
75
+ safeToAutoRepair: Boolean(options.safeToAutoRepair),
76
+ }
77
+ }
78
+
79
+ function compactRisks(state, limit) {
80
+ const residualRisks = Array.isArray(state.residualRisks) ? state.residualRisks : []
81
+ const keep = residualRisks.slice(0, limit)
82
+ const overflow = residualRisks.slice(limit)
83
+ const archive = Array.isArray(state.riskArchive) ? state.riskArchive : []
84
+ return {
85
+ ...state,
86
+ residualRisks: keep,
87
+ riskArchive: [
88
+ ...archive,
89
+ ...overflow.map((risk) => ({
90
+ archivedAt: new Date().toISOString().slice(0, 10),
91
+ risk,
92
+ resolution: 'Archived by GSE state repair to keep active residual risks compact.',
93
+ })),
94
+ ],
95
+ }
96
+ }
97
+
98
+ function latestEvidenceFileExists(target, latest) {
99
+ return latest?.evidenceFile ? fs.existsSync(path.join(target, latest.evidenceFile)) : false
100
+ }
101
+
102
+ export function auditStateRepair(target, options = {}) {
103
+ const resolvedTarget = path.resolve(target)
104
+ const writeChanges = Boolean(options.write)
105
+ const riskLimit = Number(options.maxActiveRisks ?? maxActiveRisks)
106
+ const riskLengthLimit = Number(options.maxRiskLength ?? maxRiskLength)
107
+ const gseDir = path.join(resolvedTarget, '.gse')
108
+ const statePath = path.join(gseDir, 'state.json')
109
+ const evidenceIndexPath = path.join(gseDir, 'evidence', 'index.jsonl')
110
+ const stateResult = readJson(statePath)
111
+ const evidenceIndex = readJsonl(evidenceIndexPath)
112
+ const state = stateResult.ok ? stateResult.data : null
113
+ const latestEvidence = evidenceIndex.records.at(-1) ?? null
114
+ const actions = []
115
+ const writes = []
116
+
117
+ if (!fs.existsSync(gseDir)) {
118
+ actions.push(repairAction(
119
+ 'SR01',
120
+ 'hard',
121
+ '.gse',
122
+ 'Missing .gse directory.',
123
+ 'node <gse-skill>/scripts/init-project.mjs --target <project-root> --mode auto --json',
124
+ ))
125
+ }
126
+
127
+ if (!stateResult.ok) {
128
+ actions.push(repairAction(
129
+ 'SR02',
130
+ 'hard',
131
+ '.gse/state.json',
132
+ stateResult.exists ? `Invalid JSON: ${stateResult.error}` : 'Missing state.json.',
133
+ stateResult.exists
134
+ ? 'Back up .gse/state.json, inspect the JSON error, then run node <gse-skill>/scripts/update-project-state.mjs --target <project-root> --force --json only if rebuilding from project docs is acceptable.'
135
+ : 'node <gse-skill>/scripts/update-project-state.mjs --target <project-root> --json',
136
+ ))
137
+ }
138
+
139
+ if (!evidenceIndex.ok) {
140
+ actions.push(repairAction(
141
+ 'SR03',
142
+ 'hard',
143
+ '.gse/evidence/index.jsonl',
144
+ evidenceIndex.exists ? `Invalid JSONL: ${evidenceIndex.error}` : 'Missing evidence index.',
145
+ evidenceIndex.exists
146
+ ? 'Back up .gse/evidence/index.jsonl, fix the reported line, and rerun /gse continue before implementation.'
147
+ : 'node <gse-skill>/scripts/update-project-state.mjs --target <project-root> --json',
148
+ ))
149
+ }
150
+
151
+ if (state) {
152
+ const residualRisks = Array.isArray(state.residualRisks) ? state.residualRisks : []
153
+ const longRisks = residualRisks.filter((risk) => String(risk).length > riskLengthLimit)
154
+ if (!Array.isArray(state.residualRisks)) {
155
+ actions.push(repairAction(
156
+ 'SR04',
157
+ 'warning',
158
+ '.gse/state.json',
159
+ 'residualRisks is missing or is not an array.',
160
+ 'Set residualRisks to an explicit array; use [] only when there are no known residual risks.',
161
+ ))
162
+ } else if (residualRisks.length > riskLimit) {
163
+ actions.push(repairAction(
164
+ 'SR05',
165
+ 'warning',
166
+ '.gse/state.json',
167
+ `${residualRisks.length} active residual risks exceed compact limit ${riskLimit}.`,
168
+ 'node <gse-skill>/scripts/run-gse-command.mjs --target <project-root> --command "/gse repair" --execute --json',
169
+ { writeSupported: true, safeToAutoRepair: true },
170
+ ))
171
+ if (writeChanges) {
172
+ const backupPath = backupFile(statePath)
173
+ const repairedState = compactRisks(state, riskLimit)
174
+ fs.writeFileSync(statePath, JSON.stringify(repairedState, null, 2) + '\n', 'utf8')
175
+ writes.push({
176
+ action: 'compact-residual-risks',
177
+ targetPath: '.gse/state.json',
178
+ backupPath: backupPath ? relative(resolvedTarget, backupPath) : null,
179
+ kept: repairedState.residualRisks.length,
180
+ archived: residualRisks.length - repairedState.residualRisks.length,
181
+ })
182
+ }
183
+ }
184
+ if (longRisks.length) {
185
+ actions.push(repairAction(
186
+ 'SR06',
187
+ 'warning',
188
+ '.gse/state.json',
189
+ `${longRisks.length} residual risk(s) exceed ${riskLengthLimit} characters.`,
190
+ 'Shorten active risks to current decision-useful summaries and move detail into riskArchive or the evidence log.',
191
+ ))
192
+ }
193
+ }
194
+
195
+ if (state && evidenceIndex.ok && evidenceIndex.records.length > 0) {
196
+ if (state.lastEvidence && latestEvidence?.evidenceFile && state.lastEvidence !== latestEvidence.evidenceFile) {
197
+ actions.push(repairAction(
198
+ 'SR07',
199
+ 'warning',
200
+ '.gse/state.json',
201
+ `lastEvidence points to ${state.lastEvidence}, but latest evidence index record points to ${latestEvidence.evidenceFile}.`,
202
+ 'Update lastEvidence to the latest evidence file after confirming the newest record belongs to the current project state.',
203
+ ))
204
+ }
205
+ if (latestEvidence?.evidenceFile && !latestEvidenceFileExists(resolvedTarget, latestEvidence)) {
206
+ actions.push(repairAction(
207
+ 'SR08',
208
+ 'hard',
209
+ '.gse/evidence/index.jsonl',
210
+ `Latest evidence file is missing: ${latestEvidence.evidenceFile}.`,
211
+ 'Restore the referenced evidence file or append a new evidence record that points to an existing file.',
212
+ ))
213
+ }
214
+ if (
215
+ state.currentSlice?.nextAction &&
216
+ latestEvidence?.nextAction &&
217
+ state.currentSlice.nextAction !== latestEvidence.nextAction
218
+ ) {
219
+ actions.push(repairAction(
220
+ 'SR09',
221
+ 'warning',
222
+ '.gse/state.json',
223
+ 'currentSlice.nextAction differs from the latest evidence nextAction.',
224
+ 'Confirm whether state or evidence is newer; update only the stale side before selecting an implementation slice.',
225
+ ))
226
+ }
227
+ }
228
+
229
+ const hardActions = actions.filter((item) => item.severity === 'hard')
230
+ const warningActions = actions.filter((item) => item.severity === 'warning')
231
+ return {
232
+ root,
233
+ target: resolvedTarget,
234
+ generatedAt: new Date().toISOString(),
235
+ write: writeChanges,
236
+ summary: {
237
+ status: hardActions.length ? 'repair-required' : warningActions.length ? 'repair-advised' : 'clean',
238
+ hard: hardActions.length,
239
+ warnings: warningActions.length,
240
+ actions: actions.length,
241
+ writes: writes.length,
242
+ },
243
+ state: {
244
+ exists: stateResult.exists,
245
+ valid: stateResult.ok,
246
+ currentSliceId: state?.currentSlice?.id ?? null,
247
+ nextAction: state?.currentSlice?.nextAction ?? null,
248
+ residualRisks: Array.isArray(state?.residualRisks) ? state.residualRisks.length : null,
249
+ riskArchive: Array.isArray(state?.riskArchive) ? state.riskArchive.length : null,
250
+ },
251
+ evidenceIndex: {
252
+ exists: evidenceIndex.exists,
253
+ valid: evidenceIndex.ok,
254
+ records: evidenceIndex.records.length,
255
+ latestEvidenceFile: latestEvidence?.evidenceFile ?? null,
256
+ latestNextAction: latestEvidence?.nextAction ?? null,
257
+ },
258
+ repairActions: actions,
259
+ writes,
260
+ limits: [
261
+ 'Default mode is diagnostic; it does not modify project files.',
262
+ 'Automatic writes are limited to reversible residual-risk compaction with a backup.',
263
+ 'Invalid JSON/JSONL is not guessed or overwritten; repair the reported file or rebuild state from project docs deliberately.',
264
+ ],
265
+ }
266
+ }
267
+
268
+ function createFixture(kind) {
269
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), `gse-state-repair-${kind}-`))
270
+ fs.mkdirSync(path.join(dir, '.gse', 'evidence'), { recursive: true })
271
+ fs.writeFileSync(path.join(dir, '.gse', 'README.md'), '# GSE\n', 'utf8')
272
+ const state = {
273
+ schemaVersion: 1,
274
+ projectName: 'repair-fixture',
275
+ mode: 'standard',
276
+ canonicalPlan: '',
277
+ phase: 'execute',
278
+ currentSlice: {
279
+ id: 'repair-fixture',
280
+ outcome: 'Repair fixture.',
281
+ status: 'verified',
282
+ nextAction: kind === 'stale' ? 'Stale state action.' : 'Run next repair fixture.',
283
+ },
284
+ lastEvidence: '.gse/evidence/2026-07-08.md',
285
+ residualRisks: kind === 'overlong'
286
+ ? Array.from({ length: 9 }, (_, index) => `Fixture risk ${index + 1}.`)
287
+ : ['Fixture risk.'],
288
+ riskArchive: [],
289
+ }
290
+ if (kind === 'bad-state') fs.writeFileSync(path.join(dir, '.gse', 'state.json'), '{ bad json\n', 'utf8')
291
+ else fs.writeFileSync(path.join(dir, '.gse', 'state.json'), JSON.stringify(state, null, 2) + '\n', 'utf8')
292
+ const record = {
293
+ date: '2026-07-08',
294
+ recordType: 'slice',
295
+ status: 'verified',
296
+ evidenceLevel: 'verified-unit',
297
+ requiredEvidenceLevel: 'verified-unit',
298
+ summary: 'Repair fixture evidence.',
299
+ evidenceFile: '.gse/evidence/2026-07-08.md',
300
+ commands: ['fixture'],
301
+ nextAction: 'Run next repair fixture.',
302
+ }
303
+ fs.writeFileSync(path.join(dir, '.gse', 'evidence', '2026-07-08.md'), '# Evidence\n', 'utf8')
304
+ fs.writeFileSync(
305
+ path.join(dir, '.gse', 'evidence', 'index.jsonl'),
306
+ kind === 'bad-jsonl' ? '{"date":"2026-07-08"\n' : JSON.stringify(record) + '\n',
307
+ 'utf8',
308
+ )
309
+ return dir
310
+ }
311
+
312
+ function runSelfTest() {
313
+ const clean = createFixture('clean')
314
+ const badState = createFixture('bad-state')
315
+ const badJsonl = createFixture('bad-jsonl')
316
+ const overlong = createFixture('overlong')
317
+ const stale = createFixture('stale')
318
+ const writeFixture = createFixture('overlong')
319
+ const reports = {
320
+ clean: auditStateRepair(clean),
321
+ badState: auditStateRepair(badState),
322
+ badJsonl: auditStateRepair(badJsonl),
323
+ overlong: auditStateRepair(overlong),
324
+ stale: auditStateRepair(stale),
325
+ write: auditStateRepair(writeFixture, { write: true }),
326
+ }
327
+ const checks = [
328
+ { id: 'SR-T01', status: reports.clean.summary.status === 'clean' ? 'passed' : 'failed', evidence: reports.clean.summary.status },
329
+ { id: 'SR-T02', status: reports.badState.repairActions.some((item) => item.id === 'SR02' && item.severity === 'hard') ? 'passed' : 'failed', evidence: 'bad state fixture' },
330
+ { id: 'SR-T03', status: reports.badJsonl.repairActions.some((item) => item.id === 'SR03' && item.severity === 'hard') ? 'passed' : 'failed', evidence: 'bad JSONL fixture' },
331
+ { id: 'SR-T04', status: reports.overlong.repairActions.some((item) => item.id === 'SR05' && item.safeToAutoRepair) ? 'passed' : 'failed', evidence: 'overlong risk fixture' },
332
+ { id: 'SR-T05', status: reports.stale.repairActions.some((item) => item.id === 'SR09') ? 'passed' : 'failed', evidence: 'stale nextAction fixture' },
333
+ {
334
+ id: 'SR-T06',
335
+ status: reports.write.writes.some((item) => item.action === 'compact-residual-risks' && String(item.backupPath).startsWith('.gse/backups/')) && reports.write.state.residualRisks === 9 ? 'passed' : 'failed',
336
+ evidence: 'write report keeps pre-write count and records .gse backup',
337
+ },
338
+ ]
339
+ const passed = checks.filter((item) => item.status === 'passed').length
340
+ const failed = checks.length - passed
341
+ for (const dir of [clean, badState, badJsonl, overlong, stale, writeFixture]) fs.rmSync(dir, { recursive: true, force: true })
342
+ return {
343
+ root,
344
+ generatedAt: new Date().toISOString(),
345
+ summary: { status: failed === 0 ? 'passed' : 'failed', passed, failed, total: checks.length },
346
+ workflows: { stateRepairPath: failed === 0 ? 'verified' : 'failed' },
347
+ checks,
348
+ }
349
+ }
350
+
351
+ const isCli = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
352
+
353
+ if (isCli) {
354
+ const report = selfTest ? runSelfTest() : auditStateRepair(targetArg, { write })
355
+
356
+ if (jsonOnly) console.log(JSON.stringify(report, null, 2))
357
+ else console.log(JSON.stringify(report, null, 2))
358
+
359
+ if (report.summary.status === 'failed' || report.summary.status === 'repair-required') process.exit(1)
360
+ }
@@ -1,117 +1,117 @@
1
- #!/usr/bin/env node
2
- import fs from 'node:fs'
3
- import path from 'node:path'
4
-
5
- const args = process.argv.slice(2)
6
-
7
- function readArg(name, fallback = null) {
8
- const index = args.indexOf(name)
9
- if (index === -1) return fallback
10
- return args[index + 1] ?? fallback
11
- }
12
-
13
- const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
14
- const jsonOnly = args.includes('--json')
15
-
16
- function read(relativePath) {
17
- const fullPath = path.join(root, relativePath)
18
- return fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : ''
19
- }
20
-
21
- function exists(relativePath) {
22
- return fs.existsSync(path.join(root, relativePath))
23
- }
24
-
25
- function check(id, label, ok, evidence, risk = '') {
26
- return { id, label, status: ok ? 'passed' : 'failed', evidence, risk }
27
- }
28
-
29
- const template = read('assets/templates/target-adoption-evidence.md')
30
- const recipes = read('references/adoption-recipes.md')
31
- const discovery = read('scripts/discover-project-profile.mjs')
32
- const validate = read('scripts/validate-gse.mjs')
33
-
34
- const fields = [
35
- 'Target project:',
36
- 'Adoption path:',
37
- 'Project rules read:',
38
- 'Files inspected:',
39
- 'Files changed:',
40
- 'Commands run:',
41
- 'Detected project type:',
42
- 'Detected package manager:',
43
- 'Detected scripts:',
44
- 'Host/tool statuses:',
45
- 'Evidence status:',
46
- 'Accepted by:',
47
- 'Residual risks:',
48
- 'Next action:',
49
- ]
50
-
51
- const noOverclaim = [
52
- 'documented` until executed',
53
- 'unknown` unless the tool was actually checked',
54
- 'Do not claim arbitrary real-repo certification',
55
- 'host runtime support',
56
- 'subagent support',
57
- 'browser support',
58
- 'MCP support',
59
- 'CI support',
60
- 'release publication',
61
- 'owner acceptance',
62
- 'Accepted by: not accepted',
63
- ]
64
-
65
- const checks = [
66
- check('TAE01', 'target adoption evidence template exists', exists('assets/templates/target-adoption-evidence.md'), 'assets/templates/target-adoption-evidence.md'),
67
- check('TAE02', 'template captures target-project evidence fields', fields.every((item) => template.includes(item)), fields.join(', ')),
68
- check('TAE03', 'template prevents real-repo and host capability overclaims', noOverclaim.every((item) => template.includes(item)), 'anti-overclaim rules'),
69
- check('TAE04', 'adoption recipes route real target evidence to template', recipes.includes('assets/templates/target-adoption-evidence.md') && recipes.includes('Accepted by: not accepted'), 'references/adoption-recipes.md'),
70
- check('TAE05', 'discovery captures namespaced project scripts', discovery.includes('/^(smoke|evidence|replay|eval|release|deploy|publish|electron):/') && discovery.includes('package.json smoke script'), 'scripts/discover-project-profile.mjs'),
71
- check('TAE06', 'consolidated validator includes this audit', validate.includes('audit-target-adoption-evidence.mjs'), 'scripts/validate-gse.mjs'),
72
- ]
73
-
74
- const passed = checks.filter((item) => item.status === 'passed').length
75
- const failed = checks.length - passed
76
- const report = {
77
- root,
78
- generatedAt: new Date().toISOString(),
79
- summary: { status: failed === 0 ? 'passed' : 'failed', passed, failed, total: checks.length },
80
- workflows: { targetAdoptionEvidence: failed === 0 ? 'verified' : 'failed' },
81
- limits: [
82
- 'This audit verifies the target-project evidence template and discovery support only.',
83
- 'It does not certify any arbitrary repository or accept a host/runtime capability.',
84
- ],
85
- checks,
86
- }
87
-
88
- function renderMarkdown(data) {
89
- const lines = []
90
- lines.push('# GSE Target Adoption Evidence Audit')
91
- lines.push('')
92
- lines.push('Generated: ' + data.generatedAt)
93
- lines.push('Root: ' + data.root)
94
- lines.push('')
95
- lines.push('## Summary')
96
- lines.push('')
97
- lines.push('- Status: ' + data.summary.status)
98
- lines.push('- Checks: ' + data.summary.passed + '/' + data.summary.total)
99
- lines.push('- Target adoption evidence: ' + data.workflows.targetAdoptionEvidence)
100
- lines.push('')
101
- lines.push('## Checks')
102
- lines.push('')
103
- for (const item of data.checks) {
104
- const marker = item.status === 'passed' ? '[x]' : '[ ]'
105
- lines.push('- ' + marker + ' ' + item.id + ' ' + item.label + ': ' + item.evidence)
106
- }
107
- lines.push('')
108
- lines.push('## Limits')
109
- lines.push('')
110
- for (const item of data.limits) lines.push('- ' + item)
111
- return lines.join('\n') + '\n'
112
- }
113
-
114
- if (jsonOnly) console.log(JSON.stringify(report, null, 2))
115
- else console.log(renderMarkdown(report))
116
-
117
- if (failed > 0) process.exit(1)
1
+ #!/usr/bin/env node
2
+ import fs from 'node:fs'
3
+ import path from 'node:path'
4
+
5
+ const args = process.argv.slice(2)
6
+
7
+ function readArg(name, fallback = null) {
8
+ const index = args.indexOf(name)
9
+ if (index === -1) return fallback
10
+ return args[index + 1] ?? fallback
11
+ }
12
+
13
+ const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
14
+ const jsonOnly = args.includes('--json')
15
+
16
+ function read(relativePath) {
17
+ const fullPath = path.join(root, relativePath)
18
+ return fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : ''
19
+ }
20
+
21
+ function exists(relativePath) {
22
+ return fs.existsSync(path.join(root, relativePath))
23
+ }
24
+
25
+ function check(id, label, ok, evidence, risk = '') {
26
+ return { id, label, status: ok ? 'passed' : 'failed', evidence, risk }
27
+ }
28
+
29
+ const template = read('assets/templates/target-adoption-evidence.md')
30
+ const recipes = read('references/adoption-recipes.md')
31
+ const discovery = read('scripts/discover-project-profile.mjs')
32
+ const validate = read('scripts/validate-gse.mjs')
33
+
34
+ const fields = [
35
+ 'Target project:',
36
+ 'Adoption path:',
37
+ 'Project rules read:',
38
+ 'Files inspected:',
39
+ 'Files changed:',
40
+ 'Commands run:',
41
+ 'Detected project type:',
42
+ 'Detected package manager:',
43
+ 'Detected scripts:',
44
+ 'Host/tool statuses:',
45
+ 'Evidence status:',
46
+ 'Accepted by:',
47
+ 'Residual risks:',
48
+ 'Next action:',
49
+ ]
50
+
51
+ const noOverclaim = [
52
+ 'documented` until executed',
53
+ 'unknown` unless the tool was actually checked',
54
+ 'Do not claim arbitrary real-repo certification',
55
+ 'host runtime support',
56
+ 'subagent support',
57
+ 'browser support',
58
+ 'MCP support',
59
+ 'CI support',
60
+ 'release publication',
61
+ 'owner acceptance',
62
+ 'Accepted by: not accepted',
63
+ ]
64
+
65
+ const checks = [
66
+ check('TAE01', 'target adoption evidence template exists', exists('assets/templates/target-adoption-evidence.md'), 'assets/templates/target-adoption-evidence.md'),
67
+ check('TAE02', 'template captures target-project evidence fields', fields.every((item) => template.includes(item)), fields.join(', ')),
68
+ check('TAE03', 'template prevents real-repo and host capability overclaims', noOverclaim.every((item) => template.includes(item)), 'anti-overclaim rules'),
69
+ check('TAE04', 'adoption recipes route real target evidence to template', recipes.includes('assets/templates/target-adoption-evidence.md') && recipes.includes('Accepted by: not accepted'), 'references/adoption-recipes.md'),
70
+ check('TAE05', 'discovery captures namespaced project scripts', discovery.includes('/^(smoke|evidence|replay|eval|release|deploy|publish|electron):/') && discovery.includes('package.json smoke script'), 'scripts/discover-project-profile.mjs'),
71
+ check('TAE06', 'consolidated validator includes this audit', validate.includes('audit-target-adoption-evidence.mjs'), 'scripts/validate-gse.mjs'),
72
+ ]
73
+
74
+ const passed = checks.filter((item) => item.status === 'passed').length
75
+ const failed = checks.length - passed
76
+ const report = {
77
+ root,
78
+ generatedAt: new Date().toISOString(),
79
+ summary: { status: failed === 0 ? 'passed' : 'failed', passed, failed, total: checks.length },
80
+ workflows: { targetAdoptionEvidence: failed === 0 ? 'verified' : 'failed' },
81
+ limits: [
82
+ 'This audit verifies the target-project evidence template and discovery support only.',
83
+ 'It does not certify any arbitrary repository or accept a host/runtime capability.',
84
+ ],
85
+ checks,
86
+ }
87
+
88
+ function renderMarkdown(data) {
89
+ const lines = []
90
+ lines.push('# GSE Target Adoption Evidence Audit')
91
+ lines.push('')
92
+ lines.push('Generated: ' + data.generatedAt)
93
+ lines.push('Root: ' + data.root)
94
+ lines.push('')
95
+ lines.push('## Summary')
96
+ lines.push('')
97
+ lines.push('- Status: ' + data.summary.status)
98
+ lines.push('- Checks: ' + data.summary.passed + '/' + data.summary.total)
99
+ lines.push('- Target adoption evidence: ' + data.workflows.targetAdoptionEvidence)
100
+ lines.push('')
101
+ lines.push('## Checks')
102
+ lines.push('')
103
+ for (const item of data.checks) {
104
+ const marker = item.status === 'passed' ? '[x]' : '[ ]'
105
+ lines.push('- ' + marker + ' ' + item.id + ' ' + item.label + ': ' + item.evidence)
106
+ }
107
+ lines.push('')
108
+ lines.push('## Limits')
109
+ lines.push('')
110
+ for (const item of data.limits) lines.push('- ' + item)
111
+ return lines.join('\n') + '\n'
112
+ }
113
+
114
+ if (jsonOnly) console.log(JSON.stringify(report, null, 2))
115
+ else console.log(renderMarkdown(report))
116
+
117
+ if (failed > 0) process.exit(1)