@nazty_labs/common-ground 0.5.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 (62) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +64 -0
  3. package/SETUP.md +219 -0
  4. package/dist/access.d.ts +172 -0
  5. package/dist/access.js +175 -0
  6. package/dist/cli.d.ts +2 -0
  7. package/dist/cli.js +198 -0
  8. package/dist/commands.d.ts +189 -0
  9. package/dist/commands.js +202 -0
  10. package/dist/discovery.d.ts +73 -0
  11. package/dist/discovery.js +417 -0
  12. package/dist/errors.d.ts +15 -0
  13. package/dist/errors.js +22 -0
  14. package/dist/export.d.ts +14 -0
  15. package/dist/export.js +86 -0
  16. package/dist/guidance.d.ts +11 -0
  17. package/dist/guidance.js +75 -0
  18. package/dist/hooks.d.ts +4 -0
  19. package/dist/hooks.js +141 -0
  20. package/dist/init.d.ts +304 -0
  21. package/dist/init.js +150 -0
  22. package/dist/maintenance.d.ts +126 -0
  23. package/dist/maintenance.js +23 -0
  24. package/dist/matching.d.ts +17 -0
  25. package/dist/matching.js +32 -0
  26. package/dist/model.d.ts +974 -0
  27. package/dist/model.js +21 -0
  28. package/dist/navigation.d.ts +164 -0
  29. package/dist/navigation.js +164 -0
  30. package/dist/operations.d.ts +10 -0
  31. package/dist/operations.js +130 -0
  32. package/dist/paging.d.ts +5 -0
  33. package/dist/paging.js +32 -0
  34. package/dist/retrieval.d.ts +146 -0
  35. package/dist/retrieval.js +150 -0
  36. package/dist/review-files.d.ts +3 -0
  37. package/dist/review-files.js +106 -0
  38. package/dist/review.d.ts +86 -0
  39. package/dist/review.js +124 -0
  40. package/dist/server.d.ts +8 -0
  41. package/dist/server.js +105 -0
  42. package/dist/source-search.d.ts +63 -0
  43. package/dist/source-search.js +245 -0
  44. package/dist/store.d.ts +452 -0
  45. package/dist/store.js +718 -0
  46. package/dist/version.d.ts +1 -0
  47. package/dist/version.js +2 -0
  48. package/dist/workflow.d.ts +450 -0
  49. package/dist/workflow.js +317 -0
  50. package/docs/architecture.md +65 -0
  51. package/docs/audit-0.4.0.md +42 -0
  52. package/docs/demo.md +42 -0
  53. package/docs/discovery.md +70 -0
  54. package/docs/knowledge-policy.md +51 -0
  55. package/docs/pillar-contract.md +98 -0
  56. package/docs/quiet-workflow.md +98 -0
  57. package/docs/releases.md +157 -0
  58. package/package.json +52 -0
  59. package/schemas/admission.schema.json +75 -0
  60. package/schemas/knowledge.schema.json +192 -0
  61. package/schemas/patch.schema.json +220 -0
  62. package/schemas/update.schema.json +218 -0
package/schemas/knowledge.schema.json ADDED
@@ -0,0 +1,192 @@
1
+ {
2
+ "$ref": "#/definitions/knowledge",
3
+ "definitions": {
4
+ "knowledge": {
5
+ "type": "object",
6
+ "properties": {
7
+ "schemaVersion": {
8
+ "type": "number",
9
+ "const": 2
10
+ },
11
+ "pillars": {
12
+ "type": "array",
13
+ "items": {
14
+ "type": "object",
15
+ "properties": {
16
+ "id": {
17
+ "type": "string",
18
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
19
+ },
20
+ "title": {
21
+ "type": "string",
22
+ "minLength": 3,
23
+ "maxLength": 100
24
+ },
25
+ "scope": {
26
+ "type": "string",
27
+ "minLength": 12,
28
+ "maxLength": 800
29
+ },
30
+ "excludes": {
31
+ "type": "string",
32
+ "minLength": 3,
33
+ "maxLength": 800
34
+ },
35
+ "chapters": {
36
+ "type": "array",
37
+ "items": {
38
+ "type": "object",
39
+ "properties": {
40
+ "id": {
41
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/id"
42
+ },
43
+ "title": {
44
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/title"
45
+ },
46
+ "scope": {
47
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/scope"
48
+ },
49
+ "excludes": {
50
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/excludes"
51
+ },
52
+ "paths": {
53
+ "type": "array",
54
+ "items": {
55
+ "allOf": [
56
+ {
57
+ "type": "string",
58
+ "minLength": 1
59
+ },
60
+ {
61
+ "type": "string",
62
+ "minLength": 1
63
+ }
64
+ ],
65
+ "description": "Repository-relative path without traversal or symlinks; trailing directory slashes normalize away."
66
+ },
67
+ "minItems": 1,
68
+ "maxItems": 30
69
+ },
70
+ "revision": {
71
+ "type": "integer",
72
+ "exclusiveMinimum": 0
73
+ },
74
+ "facts": {
75
+ "type": "array",
76
+ "items": {
77
+ "type": "object",
78
+ "properties": {
79
+ "id": {
80
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/id"
81
+ },
82
+ "statement": {
83
+ "type": "string",
84
+ "minLength": 8,
85
+ "maxLength": 2000
86
+ },
87
+ "evidence": {
88
+ "type": "array",
89
+ "items": {
90
+ "type": "object",
91
+ "properties": {
92
+ "path": {
93
+ "allOf": [
94
+ {
95
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/chapters/items/properties/paths/items/allOf/0"
96
+ },
97
+ {
98
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/chapters/items/properties/paths/items/allOf/1"
99
+ }
100
+ ],
101
+ "description": "Supporting source path; may be outside the owning chapter. Evidence paths are automatically tracked for freshness without adding them to sourceScope."
102
+ },
103
+ "quote": {
104
+ "type": "string",
105
+ "minLength": 1,
106
+ "maxLength": 1200
107
+ }
108
+ },
109
+ "required": [
110
+ "path",
111
+ "quote"
112
+ ],
113
+ "additionalProperties": false
114
+ },
115
+ "minItems": 1,
116
+ "maxItems": 8
117
+ },
118
+ "sourceScope": {
119
+ "type": "array",
120
+ "items": {
121
+ "$ref": "#/definitions/knowledge/properties/pillars/items/properties/chapters/items/properties/paths/items"
122
+ },
123
+ "minItems": 1,
124
+ "description": "Owned source coverage, restricted to this chapter paths. For a chapter owning src: sourceScope [src], evidence [{path: shared/config.ts, quote: mode = 1}]. Cross-chapter citations belong in evidence, not sourceScope."
125
+ },
126
+ "dependsOn": {
127
+ "type": "array",
128
+ "items": {
129
+ "type": "string",
130
+ "pattern": "^[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
131
+ },
132
+ "default": []
133
+ }
134
+ },
135
+ "required": [
136
+ "id",
137
+ "statement",
138
+ "evidence",
139
+ "sourceScope"
140
+ ],
141
+ "additionalProperties": false
142
+ }
143
+ },
144
+ "sources": {
145
+ "type": "object",
146
+ "additionalProperties": {
147
+ "type": "string"
148
+ }
149
+ },
150
+ "dependencyFingerprints": {
151
+ "type": "object",
152
+ "additionalProperties": {
153
+ "type": "string"
154
+ },
155
+ "default": {}
156
+ }
157
+ },
158
+ "required": [
159
+ "id",
160
+ "title",
161
+ "scope",
162
+ "excludes",
163
+ "paths",
164
+ "revision",
165
+ "facts",
166
+ "sources"
167
+ ],
168
+ "additionalProperties": false
169
+ },
170
+ "minItems": 1
171
+ }
172
+ },
173
+ "required": [
174
+ "id",
175
+ "title",
176
+ "scope",
177
+ "excludes",
178
+ "chapters"
179
+ ],
180
+ "additionalProperties": false
181
+ }
182
+ }
183
+ },
184
+ "required": [
185
+ "schemaVersion",
186
+ "pillars"
187
+ ],
188
+ "additionalProperties": false
189
+ }
190
+ },
191
+ "$schema": "http://json-schema.org/draft-07/schema#"
192
+ }
package/schemas/patch.schema.json ADDED
@@ -0,0 +1,220 @@
1
+ {
2
+ "$ref": "#/definitions/patch",
3
+ "definitions": {
4
+ "patch": {
5
+ "type": "object",
6
+ "properties": {
7
+ "taskId": {
8
+ "type": "string",
9
+ "format": "uuid"
10
+ },
11
+ "chapterId": {
12
+ "type": "string",
13
+ "pattern": "^[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
14
+ },
15
+ "factIds": {
16
+ "type": "array",
17
+ "items": {
18
+ "type": "string",
19
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
20
+ },
21
+ "minItems": 1
22
+ },
23
+ "touchedPaths": {
24
+ "type": "array",
25
+ "items": {
26
+ "allOf": [
27
+ {
28
+ "type": "string",
29
+ "minLength": 1
30
+ },
31
+ {
32
+ "type": "string",
33
+ "minLength": 1
34
+ }
35
+ ],
36
+ "description": "Repository-relative path without traversal or symlinks; trailing directory slashes normalize away."
37
+ }
38
+ },
39
+ "tidyId": {
40
+ "type": "string",
41
+ "format": "uuid"
42
+ },
43
+ "verification": {
44
+ "type": "object",
45
+ "properties": {
46
+ "sourceFiles": {
47
+ "type": "array",
48
+ "items": {
49
+ "$ref": "#/definitions/patch/properties/touchedPaths/items"
50
+ }
51
+ },
52
+ "documentFiles": {
53
+ "type": "array",
54
+ "items": {
55
+ "$ref": "#/definitions/patch/properties/touchedPaths/items"
56
+ }
57
+ }
58
+ },
59
+ "required": [
60
+ "sourceFiles",
61
+ "documentFiles"
62
+ ],
63
+ "additionalProperties": false
64
+ },
65
+ "reviews": {
66
+ "type": "array",
67
+ "items": {
68
+ "type": "object",
69
+ "properties": {
70
+ "chapterId": {
71
+ "$ref": "#/definitions/patch/properties/chapterId"
72
+ },
73
+ "expectedRevision": {
74
+ "type": "integer",
75
+ "exclusiveMinimum": 0
76
+ },
77
+ "reviewedAllFacts": {
78
+ "type": "boolean",
79
+ "const": true
80
+ },
81
+ "replacements": {
82
+ "type": "array",
83
+ "items": {
84
+ "type": "object",
85
+ "properties": {
86
+ "id": {
87
+ "$ref": "#/definitions/patch/properties/factIds/items"
88
+ },
89
+ "statement": {
90
+ "type": "string",
91
+ "minLength": 8,
92
+ "maxLength": 2000
93
+ },
94
+ "evidence": {
95
+ "type": "array",
96
+ "items": {
97
+ "type": "object",
98
+ "properties": {
99
+ "path": {
100
+ "allOf": [
101
+ {
102
+ "$ref": "#/definitions/patch/properties/touchedPaths/items/allOf/0"
103
+ },
104
+ {
105
+ "$ref": "#/definitions/patch/properties/touchedPaths/items/allOf/1"
106
+ }
107
+ ],
108
+ "description": "Supporting source path; may be outside the owning chapter. Evidence paths are automatically tracked for freshness without adding them to sourceScope."
109
+ },
110
+ "quote": {
111
+ "type": "string",
112
+ "minLength": 1,
113
+ "maxLength": 1200
114
+ }
115
+ },
116
+ "required": [
117
+ "path",
118
+ "quote"
119
+ ],
120
+ "additionalProperties": false
121
+ },
122
+ "minItems": 1,
123
+ "maxItems": 8
124
+ },
125
+ "sourceScope": {
126
+ "type": "array",
127
+ "items": {
128
+ "$ref": "#/definitions/patch/properties/touchedPaths/items"
129
+ },
130
+ "minItems": 1,
131
+ "description": "Owned source coverage, restricted to this chapter paths. For a chapter owning src: sourceScope [src], evidence [{path: shared/config.ts, quote: mode = 1}]. Cross-chapter citations belong in evidence, not sourceScope."
132
+ },
133
+ "dependsOn": {
134
+ "type": "array",
135
+ "items": {
136
+ "type": "string",
137
+ "pattern": "^[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
138
+ },
139
+ "default": []
140
+ }
141
+ },
142
+ "required": [
143
+ "id",
144
+ "statement",
145
+ "evidence",
146
+ "sourceScope"
147
+ ],
148
+ "additionalProperties": false
149
+ },
150
+ "default": []
151
+ },
152
+ "removeFactIds": {
153
+ "type": "array",
154
+ "items": {
155
+ "type": "string"
156
+ },
157
+ "default": []
158
+ },
159
+ "reason": {
160
+ "type": "string",
161
+ "minLength": 12,
162
+ "maxLength": 1000
163
+ },
164
+ "maintenance": {
165
+ "type": "array",
166
+ "items": {
167
+ "type": "object",
168
+ "properties": {
169
+ "factId": {
170
+ "$ref": "#/definitions/patch/properties/factIds/items"
171
+ },
172
+ "action": {
173
+ "type": "string",
174
+ "enum": [
175
+ "correct",
176
+ "merge",
177
+ "remove",
178
+ "tighten"
179
+ ]
180
+ },
181
+ "reason": {
182
+ "type": "string",
183
+ "minLength": 12,
184
+ "maxLength": 1000
185
+ },
186
+ "replacement": {
187
+ "$ref": "#/definitions/patch/properties/reviews/items/properties/replacements/items/properties/dependsOn/items"
188
+ }
189
+ },
190
+ "required": [
191
+ "factId",
192
+ "action",
193
+ "reason"
194
+ ],
195
+ "additionalProperties": false
196
+ }
197
+ }
198
+ },
199
+ "required": [
200
+ "chapterId",
201
+ "expectedRevision",
202
+ "reviewedAllFacts",
203
+ "reason"
204
+ ],
205
+ "additionalProperties": false
206
+ },
207
+ "minItems": 1
208
+ }
209
+ },
210
+ "required": [
211
+ "chapterId",
212
+ "touchedPaths",
213
+ "verification",
214
+ "reviews"
215
+ ],
216
+ "additionalProperties": false
217
+ }
218
+ },
219
+ "$schema": "http://json-schema.org/draft-07/schema#"
220
+ }
package/schemas/update.schema.json ADDED
@@ -0,0 +1,218 @@
1
+ {
2
+ "$ref": "#/definitions/update",
3
+ "definitions": {
4
+ "update": {
5
+ "type": "object",
6
+ "properties": {
7
+ "chapterId": {
8
+ "type": "string",
9
+ "pattern": "^[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
10
+ },
11
+ "factIds": {
12
+ "type": "array",
13
+ "items": {
14
+ "type": "string",
15
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
16
+ },
17
+ "minItems": 1
18
+ },
19
+ "touchedPaths": {
20
+ "type": "array",
21
+ "items": {
22
+ "allOf": [
23
+ {
24
+ "type": "string",
25
+ "minLength": 1
26
+ },
27
+ {
28
+ "type": "string",
29
+ "minLength": 1
30
+ }
31
+ ],
32
+ "description": "Repository-relative path without traversal or symlinks; trailing directory slashes normalize away."
33
+ }
34
+ },
35
+ "reviews": {
36
+ "type": "array",
37
+ "items": {
38
+ "type": "object",
39
+ "properties": {
40
+ "chapterId": {
41
+ "$ref": "#/definitions/update/properties/chapterId"
42
+ },
43
+ "expectedRevision": {
44
+ "type": "integer",
45
+ "exclusiveMinimum": 0
46
+ },
47
+ "invalidatedFactIds": {
48
+ "type": "array",
49
+ "items": {
50
+ "type": "string"
51
+ }
52
+ },
53
+ "reviewedFactIds": {
54
+ "type": "array",
55
+ "items": {
56
+ "type": "string"
57
+ }
58
+ },
59
+ "facts": {
60
+ "type": "array",
61
+ "items": {
62
+ "type": "object",
63
+ "properties": {
64
+ "id": {
65
+ "$ref": "#/definitions/update/properties/factIds/items"
66
+ },
67
+ "statement": {
68
+ "type": "string",
69
+ "minLength": 8,
70
+ "maxLength": 2000
71
+ },
72
+ "evidence": {
73
+ "type": "array",
74
+ "items": {
75
+ "type": "object",
76
+ "properties": {
77
+ "path": {
78
+ "allOf": [
79
+ {
80
+ "$ref": "#/definitions/update/properties/touchedPaths/items/allOf/0"
81
+ },
82
+ {
83
+ "$ref": "#/definitions/update/properties/touchedPaths/items/allOf/1"
84
+ }
85
+ ],
86
+ "description": "Supporting source path; may be outside the owning chapter. Evidence paths are automatically tracked for freshness without adding them to sourceScope."
87
+ },
88
+ "quote": {
89
+ "type": "string",
90
+ "minLength": 1,
91
+ "maxLength": 1200
92
+ }
93
+ },
94
+ "required": [
95
+ "path",
96
+ "quote"
97
+ ],
98
+ "additionalProperties": false
99
+ },
100
+ "minItems": 1,
101
+ "maxItems": 8
102
+ },
103
+ "sourceScope": {
104
+ "type": "array",
105
+ "items": {
106
+ "$ref": "#/definitions/update/properties/touchedPaths/items"
107
+ },
108
+ "minItems": 1,
109
+ "description": "Owned source coverage, restricted to this chapter paths. For a chapter owning src: sourceScope [src], evidence [{path: shared/config.ts, quote: mode = 1}]. Cross-chapter citations belong in evidence, not sourceScope."
110
+ },
111
+ "dependsOn": {
112
+ "type": "array",
113
+ "items": {
114
+ "type": "string",
115
+ "pattern": "^[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*\\/[a-z0-9][a-z0-9-]*$"
116
+ },
117
+ "default": []
118
+ }
119
+ },
120
+ "required": [
121
+ "id",
122
+ "statement",
123
+ "evidence",
124
+ "sourceScope"
125
+ ],
126
+ "additionalProperties": false
127
+ }
128
+ },
129
+ "reason": {
130
+ "type": "string",
131
+ "minLength": 12,
132
+ "maxLength": 1000
133
+ },
134
+ "maintenance": {
135
+ "type": "array",
136
+ "items": {
137
+ "type": "object",
138
+ "properties": {
139
+ "factId": {
140
+ "$ref": "#/definitions/update/properties/factIds/items"
141
+ },
142
+ "action": {
143
+ "type": "string",
144
+ "enum": [
145
+ "correct",
146
+ "merge",
147
+ "remove",
148
+ "tighten"
149
+ ]
150
+ },
151
+ "reason": {
152
+ "type": "string",
153
+ "minLength": 12,
154
+ "maxLength": 1000
155
+ },
156
+ "replacement": {
157
+ "$ref": "#/definitions/update/properties/reviews/items/properties/facts/items/properties/dependsOn/items"
158
+ }
159
+ },
160
+ "required": [
161
+ "factId",
162
+ "action",
163
+ "reason"
164
+ ],
165
+ "additionalProperties": false
166
+ }
167
+ }
168
+ },
169
+ "required": [
170
+ "chapterId",
171
+ "expectedRevision",
172
+ "invalidatedFactIds",
173
+ "reviewedFactIds",
174
+ "facts",
175
+ "reason"
176
+ ],
177
+ "additionalProperties": false
178
+ },
179
+ "minItems": 1
180
+ },
181
+ "verification": {
182
+ "type": "object",
183
+ "properties": {
184
+ "sourceFiles": {
185
+ "type": "array",
186
+ "items": {
187
+ "$ref": "#/definitions/update/properties/touchedPaths/items"
188
+ }
189
+ },
190
+ "documentFiles": {
191
+ "type": "array",
192
+ "items": {
193
+ "$ref": "#/definitions/update/properties/touchedPaths/items"
194
+ }
195
+ }
196
+ },
197
+ "required": [
198
+ "sourceFiles",
199
+ "documentFiles"
200
+ ],
201
+ "additionalProperties": false
202
+ },
203
+ "tidyId": {
204
+ "type": "string",
205
+ "format": "uuid"
206
+ }
207
+ },
208
+ "required": [
209
+ "chapterId",
210
+ "touchedPaths",
211
+ "reviews",
212
+ "verification"
213
+ ],
214
+ "additionalProperties": false
215
+ }
216
+ },
217
+ "$schema": "http://json-schema.org/draft-07/schema#"
218
+ }