@t275005746/gse 0.1.0 → 0.1.1

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 (180) 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 +3 -4
  14. package/CHANGELOG.md +24 -24
  15. package/CONTRIBUTING.md +64 -64
  16. package/LICENSE +21 -21
  17. package/README.md +1 -1
  18. package/README.zh-CN.md +1 -1
  19. package/SECURITY.md +41 -41
  20. package/SUPPORT.md +38 -38
  21. package/assets/marketplace/README.md +7 -7
  22. package/assets/marketplace/gse-listing.json +75 -75
  23. package/assets/templates/acceptance-execution-packet.md +73 -73
  24. package/assets/templates/adr.md +14 -14
  25. package/assets/templates/change-brief.md +16 -16
  26. package/assets/templates/design.md +18 -18
  27. package/assets/templates/dispatch-packet.md +104 -104
  28. package/assets/templates/evidence.md +14 -14
  29. package/assets/templates/execution-quality-pack.md +65 -65
  30. package/assets/templates/goal-map.md +21 -21
  31. package/assets/templates/host-adapter.md +48 -48
  32. package/assets/templates/host-ui-invocation-record.md +42 -42
  33. package/assets/templates/incident-review.md +60 -60
  34. package/assets/templates/public-channel-publication-record.md +49 -49
  35. package/assets/templates/public-ci-run-record.md +53 -53
  36. package/assets/templates/public-release-record.md +65 -65
  37. package/assets/templates/public-repository-settings-record.md +59 -59
  38. package/assets/templates/public-security-contact-record.md +45 -45
  39. package/assets/templates/release-trust-record.md +32 -32
  40. package/assets/templates/review.md +18 -18
  41. package/assets/templates/spec.md +16 -16
  42. package/assets/templates/target-adoption-evidence.md +29 -29
  43. package/assets/templates/tasks.md +17 -17
  44. package/assets/templates/update-release-acceptance-record.md +58 -58
  45. package/examples/README.md +22 -22
  46. package/examples/agent-runtime-host/.claude/gse-adapter.md +6 -6
  47. package/examples/agent-runtime-host/.codex/gse-adapter.md +7 -7
  48. package/examples/agent-runtime-host/.gse/goal-map.md +7 -7
  49. package/examples/agent-runtime-host/.gse/project-profile.md +27 -27
  50. package/examples/agent-runtime-host/.gse/tooling.md +5 -5
  51. package/examples/agent-runtime-host/.mcp.json +9 -9
  52. package/examples/agent-runtime-host/AGENTS.md +5 -5
  53. package/examples/agent-runtime-host/README.md +10 -10
  54. package/examples/agent-runtime-host/docs/model-routing.md +5 -5
  55. package/examples/cli-tool/.gse/project-profile.md +21 -21
  56. package/examples/cli-tool/AGENTS.md +5 -5
  57. package/examples/cli-tool/README.md +12 -12
  58. package/examples/cli-tool/package.json +21 -21
  59. package/examples/small-app/.env.example +2 -2
  60. package/examples/small-app/.github/workflows/ci.yml +8 -8
  61. package/examples/small-app/AGENTS.md +5 -5
  62. package/examples/small-app/README.md +12 -12
  63. package/examples/small-app/package.json +26 -26
  64. package/examples/small-app/playwright.config.ts +4 -4
  65. package/package.json +53 -53
  66. package/references/adoption-recipes.md +171 -171
  67. package/references/agent-roles.md +49 -49
  68. package/references/architecture-health.md +101 -101
  69. package/references/benchmark-audit.md +73 -73
  70. package/references/community-channels.md +46 -46
  71. package/references/compatibility.md +70 -70
  72. package/references/design-basis.md +38 -38
  73. package/references/domain-model.md +129 -129
  74. package/references/domain-quality-gates.md +75 -75
  75. package/references/drift-audit.md +81 -81
  76. package/references/evidence-taxonomy.md +123 -123
  77. package/references/file-ownership.md +107 -107
  78. package/references/final-readiness.md +84 -84
  79. package/references/forward-test.md +133 -133
  80. package/references/goal-map.md +36 -36
  81. package/references/host-adapters.md +119 -119
  82. package/references/learning-system.md +35 -35
  83. package/references/marketplace-discovery.md +46 -46
  84. package/references/model-routing.md +103 -103
  85. package/references/open-source-defaults.md +39 -39
  86. package/references/operating-model.md +52 -52
  87. package/references/packaging.md +277 -277
  88. package/references/project-agent-workspace.md +89 -89
  89. package/references/project-bootstrap.md +122 -122
  90. package/references/project-profile.md +57 -57
  91. package/references/public-release.md +174 -174
  92. package/references/quality-gates.md +100 -100
  93. package/references/recovery.md +176 -176
  94. package/references/release-trust.md +43 -43
  95. package/references/release.md +126 -126
  96. package/references/review.md +141 -141
  97. package/references/router.md +90 -90
  98. package/references/spec-workflow.md +66 -66
  99. package/references/task-levels.md +81 -81
  100. package/references/tool-adapters.md +73 -73
  101. package/scripts/audit-acceptance-execution-packet.mjs +133 -133
  102. package/scripts/audit-adoption-recipes.mjs +99 -99
  103. package/scripts/audit-change-lifecycle.mjs +77 -77
  104. package/scripts/audit-change-system.mjs +134 -134
  105. package/scripts/audit-ci-readiness.mjs +107 -107
  106. package/scripts/audit-close-gate.mjs +323 -323
  107. package/scripts/audit-command-adapters.mjs +91 -91
  108. package/scripts/audit-command-execution.mjs +210 -210
  109. package/scripts/audit-compatibility.mjs +149 -149
  110. package/scripts/audit-completion-readiness.mjs +292 -292
  111. package/scripts/audit-distribution.mjs +251 -251
  112. package/scripts/audit-domain-quality-gates.mjs +108 -108
  113. package/scripts/audit-evidence-placeholders.mjs +126 -126
  114. package/scripts/audit-final-readiness-promotion.mjs +255 -255
  115. package/scripts/audit-final-readiness.mjs +226 -226
  116. package/scripts/audit-fixtures.mjs +154 -154
  117. package/scripts/audit-fresh-session-readiness.mjs +177 -177
  118. package/scripts/audit-host-runtime-evidence-handoff.mjs +159 -159
  119. package/scripts/audit-host-runtime-invocation-drill.mjs +240 -240
  120. package/scripts/audit-host-runtime-invocations.mjs +254 -254
  121. package/scripts/audit-host-ui-invocation.mjs +132 -132
  122. package/scripts/audit-marketplace-discovery.mjs +122 -122
  123. package/scripts/audit-npm-package-metadata.mjs +155 -155
  124. package/scripts/audit-npm-publish-dry-run.mjs +191 -169
  125. package/scripts/audit-npm-tarball-install.mjs +191 -191
  126. package/scripts/audit-open-source-defaults.mjs +92 -92
  127. package/scripts/audit-open-source-readiness.mjs +97 -97
  128. package/scripts/audit-project.mjs +138 -138
  129. package/scripts/audit-public-acceptance-command-dry-run-drill.mjs +203 -203
  130. package/scripts/audit-public-acceptance-readiness.mjs +224 -224
  131. package/scripts/audit-public-channel-publication.mjs +248 -248
  132. package/scripts/audit-public-ci-run.mjs +184 -184
  133. package/scripts/audit-public-collaboration-templates.mjs +98 -98
  134. package/scripts/audit-public-external-gate-probe.mjs +206 -206
  135. package/scripts/audit-public-release-decision.mjs +201 -201
  136. package/scripts/audit-public-release-metadata.mjs +176 -176
  137. package/scripts/audit-public-repository-settings.mjs +237 -237
  138. package/scripts/audit-public-security-contact.mjs +171 -171
  139. package/scripts/audit-readme-docs.mjs +6 -4
  140. package/scripts/audit-recovery-readiness.mjs +98 -98
  141. package/scripts/audit-release-readiness.mjs +106 -106
  142. package/scripts/audit-release-trust.mjs +62 -62
  143. package/scripts/audit-remote-distribution.mjs +266 -266
  144. package/scripts/audit-roadmap-consistency.mjs +235 -235
  145. package/scripts/audit-signing.mjs +147 -147
  146. package/scripts/audit-state-freshness.mjs +14 -9
  147. package/scripts/audit-target-adoption-evidence.mjs +117 -117
  148. package/scripts/audit-target-project.mjs +507 -507
  149. package/scripts/audit-update-release-acceptance.mjs +136 -136
  150. package/scripts/audit-v1-target-validation.mjs +269 -269
  151. package/scripts/audit-validation-profiles.mjs +125 -125
  152. package/scripts/close-change.mjs +116 -116
  153. package/scripts/discover-project-profile.mjs +307 -307
  154. package/scripts/generate-command-adapter.mjs +231 -231
  155. package/scripts/generate-final-acceptance-packet.mjs +181 -181
  156. package/scripts/generate-final-form-progress-report.mjs +205 -205
  157. package/scripts/generate-host-runtime-evidence-handoff.mjs +206 -206
  158. package/scripts/generate-owner-external-gate-kit.mjs +295 -295
  159. package/scripts/generate-public-acceptance-handoff.mjs +168 -168
  160. package/scripts/generate-public-release-checklist.mjs +207 -207
  161. package/scripts/generate-release-bundle.mjs +505 -505
  162. package/scripts/generate-release-owner-action-plan.mjs +172 -172
  163. package/scripts/generate-release-status-manifest.mjs +200 -200
  164. package/scripts/generate-session-prompt.mjs +188 -188
  165. package/scripts/gse.mjs +67 -67
  166. package/scripts/init-change.mjs +265 -265
  167. package/scripts/init-project.mjs +785 -785
  168. package/scripts/install-gse.mjs +234 -234
  169. package/scripts/lib/evidence-placeholders.mjs +28 -28
  170. package/scripts/package-gse.mjs +174 -174
  171. package/scripts/probe-public-external-gates.mjs +167 -167
  172. package/scripts/record-host-invocation.mjs +151 -151
  173. package/scripts/record-public-channel-publication.mjs +178 -178
  174. package/scripts/record-public-ci-run.mjs +180 -180
  175. package/scripts/record-public-release.mjs +175 -175
  176. package/scripts/record-public-repository-settings.mjs +209 -209
  177. package/scripts/record-public-security-contact.mjs +157 -157
  178. package/scripts/sign-gse-package.mjs +83 -83
  179. package/scripts/update-project-state.mjs +223 -223
  180. package/scripts/verify-gse-package.mjs +85 -85
@@ -1,123 +1,123 @@
1
- # Evidence Taxonomy
2
-
3
- Use this to decide whether work is only produced, actually verified, or accepted.
4
-
5
- GSE uses three evidence gates:
6
-
7
- ```text
8
- result -> verified -> accepted
9
- ```
10
-
11
- Do not skip gates. Do not claim a higher gate when the evidence only proves a lower gate.
12
-
13
- ## Gate 1: Result
14
-
15
- `result` means the requested artifact or change exists.
16
-
17
- Enough evidence:
18
-
19
- - File, script, template, reference, commit, report, screenshot, or generated output exists.
20
- - The change is scoped to the requested slice.
21
- - The agent can point to the exact path or output.
22
-
23
- Not enough for `result`:
24
-
25
- - A plan to create the artifact.
26
- - A final answer describing what would be changed.
27
- - A command that was intended to write a file but did not confirm the file exists.
28
-
29
- Example:
30
-
31
- - `scripts/audit-gse.mjs` exists: result.
32
- - `.gse/project-profile.md` was written in a temp fixture: result.
33
-
34
- ## Gate 2: Verified
35
-
36
- `verified` means the result was checked against acceptance criteria with evidence appropriate to the risk.
37
-
38
- Enough evidence:
39
-
40
- - Focused test, smoke, structure check, build, typecheck, lint, browser check, API check, or manual inspection directly covers the acceptance criteria.
41
- - The command output or inspected artifact proves the expected behavior.
42
- - Known residual risk is recorded.
43
-
44
- Not enough for `verified`:
45
-
46
- - The file exists but was not inspected.
47
- - A broad test passed but does not cover the changed behavior.
48
- - A command ran without checking the relevant output.
49
- - A tool is merely configured or documented but not run.
50
- - The agent says it looks right without evidence.
51
-
52
- Example:
53
-
54
- - `audit-gse.mjs` reports `GSE-C04` as `strong (2/2, score 1)` after adding `router.md`: verified for the router structural criterion.
55
- - A project profile lists Playwright as `documented` because config exists: not verified tool availability.
56
-
57
- ## Gate 3: Accepted
58
-
59
- `accepted` means the verified result has been accepted by the required authority.
60
-
61
- Enough evidence:
62
-
63
- - The user explicitly accepts the result.
64
- - A required reviewer or gate approves it.
65
- - A release, archive, or project process marks it accepted.
66
- - A pre-defined acceptance policy says verified evidence is sufficient for this task level.
67
-
68
- Not enough for `accepted`:
69
-
70
- - The agent is satisfied.
71
- - The result passed a local smoke but no acceptance policy says that is enough.
72
- - The user has not reviewed a user-facing, policy, release, or irreversible change when review is required.
73
-
74
- Example:
75
-
76
- - A focused smoke passes for an internal script: can be accepted by policy if the task is Lite or Standard and no human approval is required.
77
- - A release plan or public workflow change usually needs explicit human acceptance or release-gate acceptance.
78
-
79
- ## Required Evidence Record
80
-
81
- Every non-trivial GSE slice should record:
82
-
83
- ```text
84
- Outcome:
85
- Scope:
86
- Acceptance:
87
- Result evidence:
88
- Verification evidence:
89
- Accepted by:
90
- Residual risk:
91
- Next action:
92
- ```
93
-
94
- Use `accepted by: policy` only when the applicable policy is named, such as `Lite focused smoke policy`.
95
-
96
- For project-local GSE updates, scaffold changes, host adapter changes, and release-readiness work, use `assets/templates/update-release-acceptance-record.md` so local decisions preserved, changed files, rollback notes, owner gate, accepted-by status, residual risks, and next action are not lost.
97
-
98
- ## Status Rules
99
-
100
- - `planned`: desired but no result yet.
101
- - `result`: artifact/change exists but has not been verified.
102
- - `verified`: acceptance criteria are directly covered by evidence.
103
- - `accepted`: verified result has user, reviewer, release, archive, or policy acceptance.
104
- - `blocked`: meaningful progress cannot continue and the blocker satisfies the project's blocked rule.
105
-
106
- ## Tool Status Is Separate
107
-
108
- Do not confuse evidence gates with tool availability status.
109
-
110
- - `documented`: a file says a tool or command exists.
111
- - `verified`: the tool or command was actually run or checked.
112
- - `unknown`: no trustworthy evidence yet.
113
- - `unavailable`: expected tool is missing or failing.
114
-
115
- These tool statuses can support the evidence taxonomy, but they do not replace result/verified/accepted gates.
116
-
117
- ## Common Mistakes
118
-
119
- - Treating generated files as verified behavior.
120
- - Treating config presence as a working tool.
121
- - Treating a broad green test as evidence for a narrow change without coverage proof.
122
- - Treating an internal smoke as user acceptance for visible product behavior.
123
- - Updating goal status to complete when the evidence only proves one slice.
1
+ # Evidence Taxonomy
2
+
3
+ Use this to decide whether work is only produced, actually verified, or accepted.
4
+
5
+ GSE uses three evidence gates:
6
+
7
+ ```text
8
+ result -> verified -> accepted
9
+ ```
10
+
11
+ Do not skip gates. Do not claim a higher gate when the evidence only proves a lower gate.
12
+
13
+ ## Gate 1: Result
14
+
15
+ `result` means the requested artifact or change exists.
16
+
17
+ Enough evidence:
18
+
19
+ - File, script, template, reference, commit, report, screenshot, or generated output exists.
20
+ - The change is scoped to the requested slice.
21
+ - The agent can point to the exact path or output.
22
+
23
+ Not enough for `result`:
24
+
25
+ - A plan to create the artifact.
26
+ - A final answer describing what would be changed.
27
+ - A command that was intended to write a file but did not confirm the file exists.
28
+
29
+ Example:
30
+
31
+ - `scripts/audit-gse.mjs` exists: result.
32
+ - `.gse/project-profile.md` was written in a temp fixture: result.
33
+
34
+ ## Gate 2: Verified
35
+
36
+ `verified` means the result was checked against acceptance criteria with evidence appropriate to the risk.
37
+
38
+ Enough evidence:
39
+
40
+ - Focused test, smoke, structure check, build, typecheck, lint, browser check, API check, or manual inspection directly covers the acceptance criteria.
41
+ - The command output or inspected artifact proves the expected behavior.
42
+ - Known residual risk is recorded.
43
+
44
+ Not enough for `verified`:
45
+
46
+ - The file exists but was not inspected.
47
+ - A broad test passed but does not cover the changed behavior.
48
+ - A command ran without checking the relevant output.
49
+ - A tool is merely configured or documented but not run.
50
+ - The agent says it looks right without evidence.
51
+
52
+ Example:
53
+
54
+ - `audit-gse.mjs` reports `GSE-C04` as `strong (2/2, score 1)` after adding `router.md`: verified for the router structural criterion.
55
+ - A project profile lists Playwright as `documented` because config exists: not verified tool availability.
56
+
57
+ ## Gate 3: Accepted
58
+
59
+ `accepted` means the verified result has been accepted by the required authority.
60
+
61
+ Enough evidence:
62
+
63
+ - The user explicitly accepts the result.
64
+ - A required reviewer or gate approves it.
65
+ - A release, archive, or project process marks it accepted.
66
+ - A pre-defined acceptance policy says verified evidence is sufficient for this task level.
67
+
68
+ Not enough for `accepted`:
69
+
70
+ - The agent is satisfied.
71
+ - The result passed a local smoke but no acceptance policy says that is enough.
72
+ - The user has not reviewed a user-facing, policy, release, or irreversible change when review is required.
73
+
74
+ Example:
75
+
76
+ - A focused smoke passes for an internal script: can be accepted by policy if the task is Lite or Standard and no human approval is required.
77
+ - A release plan or public workflow change usually needs explicit human acceptance or release-gate acceptance.
78
+
79
+ ## Required Evidence Record
80
+
81
+ Every non-trivial GSE slice should record:
82
+
83
+ ```text
84
+ Outcome:
85
+ Scope:
86
+ Acceptance:
87
+ Result evidence:
88
+ Verification evidence:
89
+ Accepted by:
90
+ Residual risk:
91
+ Next action:
92
+ ```
93
+
94
+ Use `accepted by: policy` only when the applicable policy is named, such as `Lite focused smoke policy`.
95
+
96
+ For project-local GSE updates, scaffold changes, host adapter changes, and release-readiness work, use `assets/templates/update-release-acceptance-record.md` so local decisions preserved, changed files, rollback notes, owner gate, accepted-by status, residual risks, and next action are not lost.
97
+
98
+ ## Status Rules
99
+
100
+ - `planned`: desired but no result yet.
101
+ - `result`: artifact/change exists but has not been verified.
102
+ - `verified`: acceptance criteria are directly covered by evidence.
103
+ - `accepted`: verified result has user, reviewer, release, archive, or policy acceptance.
104
+ - `blocked`: meaningful progress cannot continue and the blocker satisfies the project's blocked rule.
105
+
106
+ ## Tool Status Is Separate
107
+
108
+ Do not confuse evidence gates with tool availability status.
109
+
110
+ - `documented`: a file says a tool or command exists.
111
+ - `verified`: the tool or command was actually run or checked.
112
+ - `unknown`: no trustworthy evidence yet.
113
+ - `unavailable`: expected tool is missing or failing.
114
+
115
+ These tool statuses can support the evidence taxonomy, but they do not replace result/verified/accepted gates.
116
+
117
+ ## Common Mistakes
118
+
119
+ - Treating generated files as verified behavior.
120
+ - Treating config presence as a working tool.
121
+ - Treating a broad green test as evidence for a narrow change without coverage proof.
122
+ - Treating an internal smoke as user acceptance for visible product behavior.
123
+ - Updating goal status to complete when the evidence only proves one slice.
@@ -1,107 +1,107 @@
1
- # File Ownership And Dirty Worktree
2
-
3
- Use this when GSE work touches files in a dirty worktree, uses real subagents, simulates roles sequentially, or coordinates multiple agents, branches, worktrees, or review loops.
4
-
5
- ## Core Rule
6
-
7
- Protect user work first. Then protect agent work from other agent work.
8
-
9
- A file is not safe to edit just because it is in scope. First inspect whether it already has unrelated changes, generated output, local-only edits, or another active owner.
10
-
11
- ## Ownership Levels
12
-
13
- | Level | Use when | Required action |
14
- |---|---|---|
15
- | Observe | Read-only location, review, QA, code search | Do not write. Report files inspected if useful. |
16
- | Soft claim | One agent edits a small bounded slice | State intended files before editing and keep diff scoped. |
17
- | Explicit claim | Multi-agent work, broad refactor, dirty worktree, shared files | Record owner, allowed files, forbidden files, and release condition. |
18
- | Isolated worktree | Parallel implementation, risky experiment, long-running branch | Use a separate branch/worktree when the project supports git. |
19
-
20
- Level 1 and 2 tasks should not require formal lock files. Escalate only when collision risk is real.
21
-
22
- ## Dirty Worktree Policy
23
-
24
- Before editing implementation or shared docs:
25
-
26
- 1. Check project status with the safest available command, usually `git status --short` when the directory is a git repo.
27
- 2. If the directory is not a git repo, state that git ownership evidence is unavailable and rely on file scope plus timestamps/diff if available.
28
- 3. Identify files already modified before your work.
29
- 4. Treat pre-existing changes as user or another agent changes unless evidence proves otherwise.
30
- 5. Do not revert, overwrite, format, move, or delete unrelated changes.
31
- 6. If the target file is already dirty, inspect it and merge around existing changes. Ask only if the existing change makes the requested edit ambiguous or unsafe.
32
- 7. After editing, verify the final changed-file set matches the slice.
33
-
34
- ## Claim Format
35
-
36
- Use this lightweight claim in dispatch packets, slice notes, or comments when explicit ownership is needed:
37
-
38
- For delegated or role-separated work, prefer `assets/templates/dispatch-packet.md` so the claim also includes objective, context, expected output, verification, and stop conditions.
39
-
40
- ```text
41
- Owner:
42
- Purpose:
43
- Allowed files:
44
- Forbidden files:
45
- Expected edits:
46
- Verification:
47
- Release condition:
48
- ```
49
-
50
- Claims should be short and local to the task. Do not create permanent process artifacts for one-off edits unless the project already requires them.
51
-
52
- ## Subagent And Role Rules
53
-
54
- When real subagent tools exist:
55
-
56
- - Give each subagent a role, objective, allowed files, forbidden files, and expected output.
57
- - Prefer read-only locator/reviewer/QA roles for broad exploration.
58
- - Do not dispatch parallel builders to the same files or tightly coupled modules.
59
- - Require implementers to report files changed and verification run.
60
- - Run spec review before code-quality review when both exist.
61
- - Coordinator owns final integration and evidence.
62
-
63
- When no real subagent tool exists:
64
-
65
- - Execute roles sequentially in the main session.
66
- - Say that no real subagent dispatch occurred if the distinction matters.
67
- - Keep the same ownership boundaries: locator is read-only, builder writes assigned files, reviewer is read-only, QA writes evidence only.
68
- - Do not fake parallelism, independent review, or subagent status.
69
-
70
- ## Shared File Rules
71
-
72
- Shared files include routing docs, config, package manifests, migration files, generated clients, lockfiles, schemas, shared types, and design-system primitives.
73
-
74
- For shared files:
75
-
76
- - Read surrounding patterns before editing.
77
- - Avoid formatting churn.
78
- - Keep behavior and formatting changes separate when feasible.
79
- - Check for generated-file policy before editing generated outputs.
80
- - If multiple slices need the same shared file, serialize edits through the coordinator.
81
-
82
- ## Ownership Conflicts
83
-
84
- If two tasks need the same file:
85
-
86
- 1. Prefer sequencing over parallel edits.
87
- 2. If both are small and related, merge into one slice.
88
- 3. If they are independent but touch the same file, split by branch/worktree or pick one owner.
89
- 4. If an unexpected dirty change appears, stop destructive actions, inspect the diff, and continue only if the merge path is clear.
90
- 5. Record unresolved conflict as a risk or blocker, not as completed work.
91
-
92
- ## Verification Checklist
93
-
94
- Before claiming completion:
95
-
96
- - Intended files are the only files changed, or every extra file is explained.
97
- - Pre-existing dirty files were not reverted or overwritten.
98
- - Generated/test/output artifacts are excluded unless the project requires them.
99
- - Subagent work, if any, has role, allowed files, and verification evidence.
100
- - The evidence record names focused validation and residual risk.
101
-
102
- ## Project Integration
103
-
104
- - `references/agent-roles.md` defines role responsibilities.
105
- - `references/operating-model.md` defines when ownership is checked in the execute loop.
106
- - `references/quality-gates.md` requires dirty-worktree evidence before completion.
107
- - `.gse/project-profile.md` should record project-specific branching, generated-file, and lockfile rules.
1
+ # File Ownership And Dirty Worktree
2
+
3
+ Use this when GSE work touches files in a dirty worktree, uses real subagents, simulates roles sequentially, or coordinates multiple agents, branches, worktrees, or review loops.
4
+
5
+ ## Core Rule
6
+
7
+ Protect user work first. Then protect agent work from other agent work.
8
+
9
+ A file is not safe to edit just because it is in scope. First inspect whether it already has unrelated changes, generated output, local-only edits, or another active owner.
10
+
11
+ ## Ownership Levels
12
+
13
+ | Level | Use when | Required action |
14
+ |---|---|---|
15
+ | Observe | Read-only location, review, QA, code search | Do not write. Report files inspected if useful. |
16
+ | Soft claim | One agent edits a small bounded slice | State intended files before editing and keep diff scoped. |
17
+ | Explicit claim | Multi-agent work, broad refactor, dirty worktree, shared files | Record owner, allowed files, forbidden files, and release condition. |
18
+ | Isolated worktree | Parallel implementation, risky experiment, long-running branch | Use a separate branch/worktree when the project supports git. |
19
+
20
+ Level 1 and 2 tasks should not require formal lock files. Escalate only when collision risk is real.
21
+
22
+ ## Dirty Worktree Policy
23
+
24
+ Before editing implementation or shared docs:
25
+
26
+ 1. Check project status with the safest available command, usually `git status --short` when the directory is a git repo.
27
+ 2. If the directory is not a git repo, state that git ownership evidence is unavailable and rely on file scope plus timestamps/diff if available.
28
+ 3. Identify files already modified before your work.
29
+ 4. Treat pre-existing changes as user or another agent changes unless evidence proves otherwise.
30
+ 5. Do not revert, overwrite, format, move, or delete unrelated changes.
31
+ 6. If the target file is already dirty, inspect it and merge around existing changes. Ask only if the existing change makes the requested edit ambiguous or unsafe.
32
+ 7. After editing, verify the final changed-file set matches the slice.
33
+
34
+ ## Claim Format
35
+
36
+ Use this lightweight claim in dispatch packets, slice notes, or comments when explicit ownership is needed:
37
+
38
+ For delegated or role-separated work, prefer `assets/templates/dispatch-packet.md` so the claim also includes objective, context, expected output, verification, and stop conditions.
39
+
40
+ ```text
41
+ Owner:
42
+ Purpose:
43
+ Allowed files:
44
+ Forbidden files:
45
+ Expected edits:
46
+ Verification:
47
+ Release condition:
48
+ ```
49
+
50
+ Claims should be short and local to the task. Do not create permanent process artifacts for one-off edits unless the project already requires them.
51
+
52
+ ## Subagent And Role Rules
53
+
54
+ When real subagent tools exist:
55
+
56
+ - Give each subagent a role, objective, allowed files, forbidden files, and expected output.
57
+ - Prefer read-only locator/reviewer/QA roles for broad exploration.
58
+ - Do not dispatch parallel builders to the same files or tightly coupled modules.
59
+ - Require implementers to report files changed and verification run.
60
+ - Run spec review before code-quality review when both exist.
61
+ - Coordinator owns final integration and evidence.
62
+
63
+ When no real subagent tool exists:
64
+
65
+ - Execute roles sequentially in the main session.
66
+ - Say that no real subagent dispatch occurred if the distinction matters.
67
+ - Keep the same ownership boundaries: locator is read-only, builder writes assigned files, reviewer is read-only, QA writes evidence only.
68
+ - Do not fake parallelism, independent review, or subagent status.
69
+
70
+ ## Shared File Rules
71
+
72
+ Shared files include routing docs, config, package manifests, migration files, generated clients, lockfiles, schemas, shared types, and design-system primitives.
73
+
74
+ For shared files:
75
+
76
+ - Read surrounding patterns before editing.
77
+ - Avoid formatting churn.
78
+ - Keep behavior and formatting changes separate when feasible.
79
+ - Check for generated-file policy before editing generated outputs.
80
+ - If multiple slices need the same shared file, serialize edits through the coordinator.
81
+
82
+ ## Ownership Conflicts
83
+
84
+ If two tasks need the same file:
85
+
86
+ 1. Prefer sequencing over parallel edits.
87
+ 2. If both are small and related, merge into one slice.
88
+ 3. If they are independent but touch the same file, split by branch/worktree or pick one owner.
89
+ 4. If an unexpected dirty change appears, stop destructive actions, inspect the diff, and continue only if the merge path is clear.
90
+ 5. Record unresolved conflict as a risk or blocker, not as completed work.
91
+
92
+ ## Verification Checklist
93
+
94
+ Before claiming completion:
95
+
96
+ - Intended files are the only files changed, or every extra file is explained.
97
+ - Pre-existing dirty files were not reverted or overwritten.
98
+ - Generated/test/output artifacts are excluded unless the project requires them.
99
+ - Subagent work, if any, has role, allowed files, and verification evidence.
100
+ - The evidence record names focused validation and residual risk.
101
+
102
+ ## Project Integration
103
+
104
+ - `references/agent-roles.md` defines role responsibilities.
105
+ - `references/operating-model.md` defines when ownership is checked in the execute loop.
106
+ - `references/quality-gates.md` requires dirty-worktree evidence before completion.
107
+ - `.gse/project-profile.md` should record project-specific branching, generated-file, and lockfile rules.
@@ -1,84 +1,84 @@
1
- # Final Readiness Matrix
2
-
3
- Use this when deciding whether GSE can be called open-source-ready, installable, and cross-host usable.
4
-
5
- This matrix is a claim boundary. It separates local verified capability from owner-required or external evidence. Do not collapse these states into a single "done" label.
6
-
7
- ## Status Vocabulary
8
-
9
- - `verified`: GSE has current local evidence from scripts, records, or package/install audits.
10
- - `owner-required`: the owner must make or approve a decision before the claim can become accepted.
11
- - `external-required`: a marketplace, public registry, host runtime, security contact, CI, or other external system must provide evidence.
12
- - `not-claimed`: GSE deliberately does not claim this capability.
13
-
14
- ## Readiness Areas
15
-
16
- The table below describes the baseline/status source for each row. The current truth is computed by `scripts/audit-final-readiness.mjs`; record-driven rows can promote from `owner-required` or `external-required` to `verified` only after accepted evidence records exist.
17
-
18
- | Area | Accepted claim requires | Status source / baseline |
19
- |---|---|---|
20
- | Skill structure | `SKILL.md`, references, scripts, assets, metadata, and validator pass | verified |
21
- | Project scaffold | `init-project`, project doctor, state, goal map, evidence index, close gate | verified |
22
- | Local install | package, install, installed-copy validation, package CLI entrypoint, and installed short CLI status command | verified |
23
- | npm tarball install | real local npm tarball creation, install into a clean consumer project, installed `gse` bin execution, and installed README audit | verified |
24
- | npm publish dry-run | npm publish dry-run keeps package identity, CLI bin metadata, required runtime files, and integrity fields without harmful metadata auto-correction | verified |
25
- | URL install | remote URL install, installed-copy validation, URL-installed short CLI status command, manifest integrity, and tamper rejection | verified |
26
- | Signing | package signing, verification, signed install, and tamper rejection | verified |
27
- | Open-source collaboration | README, contributing, security, support, changelog, public release metadata | verified |
28
- | CI workflow template | public repository workflow file plus local CI-readiness audit | verified |
29
- | Public CI run record | pending and accepted public CI run record mechanics | verified |
30
- | Public collaboration templates | issue and PR templates that require outcome, scope, evidence, risk, and claim boundaries | verified |
31
- | Public repository settings record | pending, verified, and accepted repository settings record mechanics | verified |
32
- | Public CI run | real public CI run URL or status-check evidence | record-driven external gate |
33
- | Public repository settings | real repository URL, issue/PR settings, branch protection, required checks, and maintainer acceptance | record-driven external gate |
34
- | License decision | owner-selected license or explicit not-public decision | record-driven owner gate |
35
- | Public security contact record | pending and accepted public security contact record mechanics | verified |
36
- | Public security contact | owner-approved vulnerability disclosure path | record-driven owner gate |
37
- | Public channel publication record | pending, registry publication, and marketplace approval record mechanics | verified |
38
- | Public registry publication | real public package or registry publication evidence | record-driven external gate |
39
- | Marketplace approval | real marketplace/catalog approval or publication evidence | record-driven external gate |
40
- | Portable command execution | `run-gse-command.mjs` command semantics audit | verified |
41
- | Host adapters | generated adapter files and compatibility matrix audit | verified |
42
- | Native slash command | verified host invocation record with native slash support | record-driven external gate |
43
- | Other host runtime invocation | verified invocation records per host | record-driven external gate |
44
-
45
- Do not read the baseline column as live status. For example, once the owner-selected license record is accepted, the audit reports `License decision` as `verified` even though the row remains an owner-gated claim type.
46
-
47
- ## Audit Command
48
-
49
- ```text
50
- node <gse-skill>/scripts/audit-final-readiness.mjs --root <gse-skill>
51
- ```
52
-
53
- The audit must report external and owner gates as incomplete unless corresponding records exist. It is valid for the audit to pass while still reporting `owner-required` or `external-required`; passing means the matrix is honest and complete, not that every external gate is satisfied.
54
-
55
- Accepted owner/external records promote final rows only when the record contains accepted evidence and the relevant boundary proof. For example, a public CI row requires an accepted public CI run record with a successful conclusion and required-check proof; a registry row requires accepted publication evidence with registry proof; native slash command support requires a host invocation record that proves native slash-command support.
56
-
57
- Use the promotion audit to verify that this path still works:
58
-
59
- ```text
60
- node <gse-skill>/scripts/audit-final-readiness-promotion.mjs --root <gse-skill>
61
- ```
62
-
63
- ## Acceptance Packet
64
-
65
- When owner-required or external-required rows remain, generate a handoff packet instead of burying follow-up work in prose:
66
-
67
- ```text
68
- node <gse-skill>/scripts/generate-final-acceptance-packet.mjs --root <gse-skill> --out <gse-skill>/.gse/acceptance/final-acceptance-packet.md --force
69
- ```
70
-
71
- The packet lists the verified local capabilities, every pending owner/external gate, the exact next evidence action, and the anti-overclaim rules. It is a continuation artifact, not acceptance by itself.
72
-
73
- ## Completion Boundary
74
-
75
- GSE can be described as locally verified and release-ready for handoff when the matrix passes and the verified rows have evidence.
76
-
77
- GSE can be described as publicly accepted only after:
78
-
79
- - owner-selected license or explicit not-public decision is recorded,
80
- - public security contact policy is approved when public release is intended,
81
- - public repository settings evidence exists when a public source repository is claimed,
82
- - public CI run evidence exists when public CI is claimed,
83
- - registry or marketplace publication evidence exists when those channels are claimed,
84
- - native slash-command support is recorded per host before it is claimed.
1
+ # Final Readiness Matrix
2
+
3
+ Use this when deciding whether GSE can be called open-source-ready, installable, and cross-host usable.
4
+
5
+ This matrix is a claim boundary. It separates local verified capability from owner-required or external evidence. Do not collapse these states into a single "done" label.
6
+
7
+ ## Status Vocabulary
8
+
9
+ - `verified`: GSE has current local evidence from scripts, records, or package/install audits.
10
+ - `owner-required`: the owner must make or approve a decision before the claim can become accepted.
11
+ - `external-required`: a marketplace, public registry, host runtime, security contact, CI, or other external system must provide evidence.
12
+ - `not-claimed`: GSE deliberately does not claim this capability.
13
+
14
+ ## Readiness Areas
15
+
16
+ The table below describes the baseline/status source for each row. The current truth is computed by `scripts/audit-final-readiness.mjs`; record-driven rows can promote from `owner-required` or `external-required` to `verified` only after accepted evidence records exist.
17
+
18
+ | Area | Accepted claim requires | Status source / baseline |
19
+ |---|---|---|
20
+ | Skill structure | `SKILL.md`, references, scripts, assets, metadata, and validator pass | verified |
21
+ | Project scaffold | `init-project`, project doctor, state, goal map, evidence index, close gate | verified |
22
+ | Local install | package, install, installed-copy validation, package CLI entrypoint, and installed short CLI status command | verified |
23
+ | npm tarball install | real local npm tarball creation, install into a clean consumer project, installed `gse` bin execution, and installed README audit | verified |
24
+ | npm publish dry-run | npm publish dry-run keeps package identity, CLI bin metadata, required runtime files, and integrity fields without harmful metadata auto-correction | verified |
25
+ | URL install | remote URL install, installed-copy validation, URL-installed short CLI status command, manifest integrity, and tamper rejection | verified |
26
+ | Signing | package signing, verification, signed install, and tamper rejection | verified |
27
+ | Open-source collaboration | README, contributing, security, support, changelog, public release metadata | verified |
28
+ | CI workflow template | public repository workflow file plus local CI-readiness audit | verified |
29
+ | Public CI run record | pending and accepted public CI run record mechanics | verified |
30
+ | Public collaboration templates | issue and PR templates that require outcome, scope, evidence, risk, and claim boundaries | verified |
31
+ | Public repository settings record | pending, verified, and accepted repository settings record mechanics | verified |
32
+ | Public CI run | real public CI run URL or status-check evidence | record-driven external gate |
33
+ | Public repository settings | real repository URL, issue/PR settings, branch protection, required checks, and maintainer acceptance | record-driven external gate |
34
+ | License decision | owner-selected license or explicit not-public decision | record-driven owner gate |
35
+ | Public security contact record | pending and accepted public security contact record mechanics | verified |
36
+ | Public security contact | owner-approved vulnerability disclosure path | record-driven owner gate |
37
+ | Public channel publication record | pending, registry publication, and marketplace approval record mechanics | verified |
38
+ | Public registry publication | real public package or registry publication evidence | record-driven external gate |
39
+ | Marketplace approval | real marketplace/catalog approval or publication evidence | record-driven external gate |
40
+ | Portable command execution | `run-gse-command.mjs` command semantics audit | verified |
41
+ | Host adapters | generated adapter files and compatibility matrix audit | verified |
42
+ | Native slash command | verified host invocation record with native slash support | record-driven external gate |
43
+ | Other host runtime invocation | verified invocation records per host | record-driven external gate |
44
+
45
+ Do not read the baseline column as live status. For example, once the owner-selected license record is accepted, the audit reports `License decision` as `verified` even though the row remains an owner-gated claim type.
46
+
47
+ ## Audit Command
48
+
49
+ ```text
50
+ node <gse-skill>/scripts/audit-final-readiness.mjs --root <gse-skill>
51
+ ```
52
+
53
+ The audit must report external and owner gates as incomplete unless corresponding records exist. It is valid for the audit to pass while still reporting `owner-required` or `external-required`; passing means the matrix is honest and complete, not that every external gate is satisfied.
54
+
55
+ Accepted owner/external records promote final rows only when the record contains accepted evidence and the relevant boundary proof. For example, a public CI row requires an accepted public CI run record with a successful conclusion and required-check proof; a registry row requires accepted publication evidence with registry proof; native slash command support requires a host invocation record that proves native slash-command support.
56
+
57
+ Use the promotion audit to verify that this path still works:
58
+
59
+ ```text
60
+ node <gse-skill>/scripts/audit-final-readiness-promotion.mjs --root <gse-skill>
61
+ ```
62
+
63
+ ## Acceptance Packet
64
+
65
+ When owner-required or external-required rows remain, generate a handoff packet instead of burying follow-up work in prose:
66
+
67
+ ```text
68
+ node <gse-skill>/scripts/generate-final-acceptance-packet.mjs --root <gse-skill> --out <gse-skill>/.gse/acceptance/final-acceptance-packet.md --force
69
+ ```
70
+
71
+ The packet lists the verified local capabilities, every pending owner/external gate, the exact next evidence action, and the anti-overclaim rules. It is a continuation artifact, not acceptance by itself.
72
+
73
+ ## Completion Boundary
74
+
75
+ GSE can be described as locally verified and release-ready for handoff when the matrix passes and the verified rows have evidence.
76
+
77
+ GSE can be described as publicly accepted only after:
78
+
79
+ - owner-selected license or explicit not-public decision is recorded,
80
+ - public security contact policy is approved when public release is intended,
81
+ - public repository settings evidence exists when a public source repository is claimed,
82
+ - public CI run evidence exists when public CI is claimed,
83
+ - registry or marketplace publication evidence exists when those channels are claimed,
84
+ - native slash-command support is recorded per host before it is claimed.