@cat-factory/contracts 0.17.0 → 0.17.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 (6) hide show
  1. package/dist/clarity.d.ts +2 -2
  2. package/dist/requirements.d.ts +94 -6
  3. package/dist/requirements.d.ts.map +1 -1
  4. package/dist/requirements.js +65 -3
  5. package/dist/requirements.js.map +1 -1
  6. package/package.json +1 -1
package/dist/clarity.d.ts CHANGED
@@ -6,7 +6,7 @@ export declare const clarityReviewItemSchema: v.ObjectSchema<{
6
6
  readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
7
7
  readonly title: v.StringSchema<undefined>;
8
8
  readonly detail: v.StringSchema<undefined>;
9
- readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
9
+ readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
10
10
  readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
11
11
  readonly createdAt: v.NumberSchema<undefined>;
12
12
  readonly updatedAt: v.NumberSchema<undefined>;
@@ -26,7 +26,7 @@ export declare const clarityReviewSchema: v.ObjectSchema<{
26
26
  readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
27
27
  readonly title: v.StringSchema<undefined>;
28
28
  readonly detail: v.StringSchema<undefined>;
29
- readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
29
+ readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
30
30
  readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
31
31
  readonly createdAt: v.NumberSchema<undefined>;
32
32
  readonly updatedAt: v.NumberSchema<undefined>;
package/dist/requirements.d.ts CHANGED
@@ -8,10 +8,13 @@ export type ReviewItemSeverity = v.InferOutput<typeof reviewItemSeveritySchema>;
8
8
  /**
9
9
  * Lifecycle of a single item: `open` until a human engages, `answered` once a
10
10
  * reply is recorded, `resolved` when accepted as done, `dismissed` when waved
11
- * off as not applicable. Both `resolved` and `dismissed` count as "settled" for
12
- * the purpose of gating incorporation.
11
+ * off as not applicable, `recommend_requested` when the human asked the Requirement
12
+ * Writer to suggest an answer instead of writing one. All of `answered`, `resolved`,
13
+ * `dismissed` and `recommend_requested` count as "settled" (not `open`) for gating
14
+ * incorporation — a finding awaiting a recommendation doesn't block the cycle, its
15
+ * recommendation simply lands for review and folds into a later pass once accepted.
13
16
  */
14
- export declare const reviewItemStatusSchema: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
17
+ export declare const reviewItemStatusSchema: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
15
18
  export type ReviewItemStatus = v.InferOutput<typeof reviewItemStatusSchema>;
16
19
  /** A single question / challenge the reviewer raised about the requirements. */
17
20
  export declare const requirementReviewItemSchema: v.ObjectSchema<{
@@ -22,7 +25,7 @@ export declare const requirementReviewItemSchema: v.ObjectSchema<{
22
25
  readonly title: v.StringSchema<undefined>;
23
26
  /** The full question / gap / challenge, in plain prose. */
24
27
  readonly detail: v.StringSchema<undefined>;
25
- readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
28
+ readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
26
29
  /** The human's answer, or null while unanswered. */
27
30
  readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
28
31
  readonly createdAt: v.NumberSchema<undefined>;
@@ -48,6 +51,48 @@ export type RequirementReviewItem = v.InferOutput<typeof requirementReviewItemSc
48
51
  */
49
52
  export declare const requirementReviewStatusSchema: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
50
53
  export type RequirementReviewStatus = v.InferOutput<typeof requirementReviewStatusSchema>;
54
+ /**
55
+ * Lifecycle of a single Requirement-Writer recommendation:
56
+ * - `ready`: the Writer produced a suggested answer; the human hasn't decided yet.
57
+ * - `accepted`: the human took the suggestion — it becomes the source finding's answer
58
+ * and folds into the NEXT incorporation pass.
59
+ * - `rejected`: the human declined it (they then dismiss / answer manually / re-request).
60
+ */
61
+ export declare const recommendationStatusSchema: v.PicklistSchema<["ready", "accepted", "rejected"], undefined>;
62
+ export type RecommendationStatus = v.InferOutput<typeof recommendationStatusSchema>;
63
+ /**
64
+ * A Requirement-Writer suggestion for one finding. Recommendations are a first-class
65
+ * collection on the review (NOT on items) so they survive the item churn each re-review
66
+ * causes — the source finding is snapshotted by title/detail rather than referenced by a
67
+ * (volatile) item id. The Writer grounds the suggestion on the project's best-practice
68
+ * fragments first, then `spec/` + `tech-spec/`, then web search; when the answer comes
69
+ * straight from a best-practice fragment, {@link groundedInFragment} carries it so the UI
70
+ * can mark the option as the current team/org standard. Recommendations are NOT AI-reviewed.
71
+ */
72
+ export declare const requirementRecommendationSchema: v.ObjectSchema<{
73
+ readonly id: v.StringSchema<undefined>;
74
+ /** Snapshot of the finding this recommends an answer for (item ids churn on re-review). */
75
+ readonly sourceFinding: v.ObjectSchema<{
76
+ readonly title: v.StringSchema<undefined>;
77
+ readonly detail: v.StringSchema<undefined>;
78
+ }, undefined>;
79
+ /** The suggested answer text. */
80
+ readonly recommendedText: v.StringSchema<undefined>;
81
+ readonly status: v.PicklistSchema<["ready", "accepted", "rejected"], undefined>;
82
+ /** A "do it differently" note the human attached when re-requesting, else null. */
83
+ readonly note: v.NullableSchema<v.StringSchema<undefined>, undefined>;
84
+ /**
85
+ * Set when the recommendation is taken directly from a best-practice fragment (the
86
+ * "current standard" signal), else null. Carries the fragment's id + title for the badge.
87
+ */
88
+ readonly groundedInFragment: v.NullableSchema<v.ObjectSchema<{
89
+ readonly id: v.StringSchema<undefined>;
90
+ readonly title: v.StringSchema<undefined>;
91
+ }, undefined>, undefined>;
92
+ readonly createdAt: v.NumberSchema<undefined>;
93
+ readonly updatedAt: v.NumberSchema<undefined>;
94
+ }, undefined>;
95
+ export type RequirementRecommendation = v.InferOutput<typeof requirementRecommendationSchema>;
51
96
  /** A completed requirements review for one board block. */
52
97
  export declare const requirementReviewSchema: v.ObjectSchema<{
53
98
  readonly id: v.StringSchema<undefined>;
@@ -61,7 +106,7 @@ export declare const requirementReviewSchema: v.ObjectSchema<{
61
106
  readonly title: v.StringSchema<undefined>;
62
107
  /** The full question / gap / challenge, in plain prose. */
63
108
  readonly detail: v.StringSchema<undefined>;
64
- readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
109
+ readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
65
110
  /** The human's answer, or null while unanswered. */
66
111
  readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
67
112
  readonly createdAt: v.NumberSchema<undefined>;
@@ -88,6 +133,33 @@ export declare const requirementReviewSchema: v.ObjectSchema<{
88
133
  * it by one.
89
134
  */
90
135
  readonly maxIterations: v.OptionalSchema<v.NumberSchema<undefined>, 1>;
136
+ /**
137
+ * Requirement-Writer suggestions awaiting (or settled by) human accept/reject. Survives
138
+ * the re-review item churn — see {@link requirementRecommendationSchema}. Empty by default.
139
+ */
140
+ readonly recommendations: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
141
+ readonly id: v.StringSchema<undefined>;
142
+ /** Snapshot of the finding this recommends an answer for (item ids churn on re-review). */
143
+ readonly sourceFinding: v.ObjectSchema<{
144
+ readonly title: v.StringSchema<undefined>;
145
+ readonly detail: v.StringSchema<undefined>;
146
+ }, undefined>;
147
+ /** The suggested answer text. */
148
+ readonly recommendedText: v.StringSchema<undefined>;
149
+ readonly status: v.PicklistSchema<["ready", "accepted", "rejected"], undefined>;
150
+ /** A "do it differently" note the human attached when re-requesting, else null. */
151
+ readonly note: v.NullableSchema<v.StringSchema<undefined>, undefined>;
152
+ /**
153
+ * Set when the recommendation is taken directly from a best-practice fragment (the
154
+ * "current standard" signal), else null. Carries the fragment's id + title for the badge.
155
+ */
156
+ readonly groundedInFragment: v.NullableSchema<v.ObjectSchema<{
157
+ readonly id: v.StringSchema<undefined>;
158
+ readonly title: v.StringSchema<undefined>;
159
+ }, undefined>, undefined>;
160
+ readonly createdAt: v.NumberSchema<undefined>;
161
+ readonly updatedAt: v.NumberSchema<undefined>;
162
+ }, undefined>, undefined>, readonly []>;
91
163
  readonly createdAt: v.NumberSchema<undefined>;
92
164
  readonly updatedAt: v.NumberSchema<undefined>;
93
165
  }, undefined>;
@@ -99,7 +171,7 @@ export declare const replyReviewItemSchema: v.ObjectSchema<{
99
171
  export type ReplyReviewItemInput = v.InferOutput<typeof replyReviewItemSchema>;
100
172
  /** Set a review item's status (resolve / dismiss / reopen). */
101
173
  export declare const updateReviewItemStatusSchema: v.ObjectSchema<{
102
- readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed"], undefined>;
174
+ readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
103
175
  }, undefined>;
104
176
  export type UpdateReviewItemStatusInput = v.InferOutput<typeof updateReviewItemStatusSchema>;
105
177
  /**
@@ -111,6 +183,22 @@ export declare const incorporateRequirementsSchema: v.ObjectSchema<{
111
183
  readonly feedback: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
112
184
  }, undefined>;
113
185
  export type IncorporateRequirementsInput = v.InferOutput<typeof incorporateRequirementsSchema>;
186
+ /**
187
+ * Ask the Requirement Writer to recommend answers for a batch of findings (by item id).
188
+ * Sent when the human marks findings "recommend something" instead of answering them.
189
+ */
190
+ export declare const requestRecommendationsSchema: v.ObjectSchema<{
191
+ readonly itemIds: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MinLengthAction<string[], 1, undefined>]>;
192
+ }, undefined>;
193
+ export type RequestRecommendationsInput = v.InferOutput<typeof requestRecommendationsSchema>;
194
+ /**
195
+ * Re-request a single recommendation with a "do it differently" note (the human rejected
196
+ * the first suggestion but wants another grounded attempt rather than answering manually).
197
+ */
198
+ export declare const reRequestRecommendationSchema: v.ObjectSchema<{
199
+ readonly note: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
200
+ }, undefined>;
201
+ export type ReRequestRecommendationInput = v.InferOutput<typeof reRequestRecommendationSchema>;
114
202
  /**
115
203
  * How a human resolves a requirements review that hit its iteration cap with findings
116
204
  * still open: `extra-round` grants one more reviewer pass, `proceed` advances the
package/dist/requirements.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAoB5B,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,yFAMnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,wDAAwC,CAAA;AAC7E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,4EAA4D,CAAA;AAC/F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E,gFAAgF;AAChF,eAAO,MAAM,2BAA2B;;;;IAItC,qCAAqC;;IAErC,2DAA2D;;;IAG3D,oDAAoD;;;;aAIpD,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,6BAA6B,4GAOxC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF,2DAA2D;AAC3D,eAAO,MAAM,uBAAuB;;;;;;;;QAxClC,qCAAqC;;QAErC,2DAA2D;;;QAG3D,oDAAoD;;;;;IAwCpD,kFAAkF;;IAElF;;;;;OAKG;;IAEH;;;;OAIG;;IAEH;;;;OAIG;;;;aAIH,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAI7E,uDAAuD;AACvD,eAAO,MAAM,qBAAqB;;aAEhC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAE9E,+DAA+D;AAC/D,eAAO,MAAM,4BAA4B;;aAEvC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAE5F;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;aAExC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC;;aAE5C,CAAA;AACF,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,WAAW,CAC1D,OAAO,iCAAiC,CACzC,CAAA;AACD,MAAM,MAAM,iCAAiC,GAAG,gCAAgC,CAAC,QAAQ,CAAC,CAAA"}
1
+ {"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"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"}
package/dist/requirements.js CHANGED
@@ -29,10 +29,19 @@ export const reviewItemSeveritySchema = v.picklist(['low', 'medium', 'high']);
29
29
  /**
30
30
  * Lifecycle of a single item: `open` until a human engages, `answered` once a
31
31
  * reply is recorded, `resolved` when accepted as done, `dismissed` when waved
32
- * off as not applicable. Both `resolved` and `dismissed` count as "settled" for
33
- * the purpose of gating incorporation.
32
+ * off as not applicable, `recommend_requested` when the human asked the Requirement
33
+ * Writer to suggest an answer instead of writing one. All of `answered`, `resolved`,
34
+ * `dismissed` and `recommend_requested` count as "settled" (not `open`) for gating
35
+ * incorporation — a finding awaiting a recommendation doesn't block the cycle, its
36
+ * recommendation simply lands for review and folds into a later pass once accepted.
34
37
  */
35
- export const reviewItemStatusSchema = v.picklist(['open', 'answered', 'resolved', 'dismissed']);
38
+ export const reviewItemStatusSchema = v.picklist([
39
+ 'open',
40
+ 'answered',
41
+ 'resolved',
42
+ 'dismissed',
43
+ 'recommend_requested',
44
+ ]);
36
45
  /** A single question / challenge the reviewer raised about the requirements. */
37
46
  export const requirementReviewItemSchema = v.object({
38
47
  id: v.string(),
@@ -73,6 +82,40 @@ export const requirementReviewStatusSchema = v.picklist([
73
82
  'exceeded',
74
83
  'incorporated',
75
84
  ]);
85
+ /**
86
+ * Lifecycle of a single Requirement-Writer recommendation:
87
+ * - `ready`: the Writer produced a suggested answer; the human hasn't decided yet.
88
+ * - `accepted`: the human took the suggestion — it becomes the source finding's answer
89
+ * and folds into the NEXT incorporation pass.
90
+ * - `rejected`: the human declined it (they then dismiss / answer manually / re-request).
91
+ */
92
+ export const recommendationStatusSchema = v.picklist(['ready', 'accepted', 'rejected']);
93
+ /**
94
+ * A Requirement-Writer suggestion for one finding. Recommendations are a first-class
95
+ * collection on the review (NOT on items) so they survive the item churn each re-review
96
+ * causes — the source finding is snapshotted by title/detail rather than referenced by a
97
+ * (volatile) item id. The Writer grounds the suggestion on the project's best-practice
98
+ * fragments first, then `spec/` + `tech-spec/`, then web search; when the answer comes
99
+ * straight from a best-practice fragment, {@link groundedInFragment} carries it so the UI
100
+ * can mark the option as the current team/org standard. Recommendations are NOT AI-reviewed.
101
+ */
102
+ export const requirementRecommendationSchema = v.object({
103
+ id: v.string(),
104
+ /** Snapshot of the finding this recommends an answer for (item ids churn on re-review). */
105
+ sourceFinding: v.object({ title: v.string(), detail: v.string() }),
106
+ /** The suggested answer text. */
107
+ recommendedText: v.string(),
108
+ status: recommendationStatusSchema,
109
+ /** A "do it differently" note the human attached when re-requesting, else null. */
110
+ note: v.nullable(v.string()),
111
+ /**
112
+ * Set when the recommendation is taken directly from a best-practice fragment (the
113
+ * "current standard" signal), else null. Carries the fragment's id + title for the badge.
114
+ */
115
+ groundedInFragment: v.nullable(v.object({ id: v.string(), title: v.string() })),
116
+ createdAt: v.number(),
117
+ updatedAt: v.number(),
118
+ });
76
119
  /** A completed requirements review for one board block. */
77
120
  export const requirementReviewSchema = v.object({
78
121
  id: v.string(),
@@ -100,6 +143,11 @@ export const requirementReviewSchema = v.object({
100
143
  * it by one.
101
144
  */
102
145
  maxIterations: v.optional(v.number(), 1),
146
+ /**
147
+ * Requirement-Writer suggestions awaiting (or settled by) human accept/reject. Survives
148
+ * the re-review item churn — see {@link requirementRecommendationSchema}. Empty by default.
149
+ */
150
+ recommendations: v.optional(v.array(requirementRecommendationSchema), []),
103
151
  createdAt: v.number(),
104
152
  updatedAt: v.number(),
105
153
  });
@@ -120,6 +168,20 @@ export const updateReviewItemStatusSchema = v.object({
120
168
  export const incorporateRequirementsSchema = v.object({
121
169
  feedback: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(4000))),
122
170
  });
171
+ /**
172
+ * Ask the Requirement Writer to recommend answers for a batch of findings (by item id).
173
+ * Sent when the human marks findings "recommend something" instead of answering them.
174
+ */
175
+ export const requestRecommendationsSchema = v.object({
176
+ itemIds: v.pipe(v.array(v.string()), v.minLength(1)),
177
+ });
178
+ /**
179
+ * Re-request a single recommendation with a "do it differently" note (the human rejected
180
+ * the first suggestion but wants another grounded attempt rather than answering manually).
181
+ */
182
+ export const reRequestRecommendationSchema = v.object({
183
+ note: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(4000)),
184
+ });
123
185
  /**
124
186
  * How a human resolves a requirements review that hit its iteration cap with findings
125
187
  * still open: `extra-round` grants one more reviewer pass, `proceed` advances the
package/dist/requirements.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"requirements.js","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"requirements.js","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cat-factory/contracts",
3
- "version": "0.17.0",
3
+ "version": "0.17.1",
4
4
  "description": "Valibot wire contract shared between the Agent Architecture Board frontend and backend.",
5
5
  "repository": {
6
6
  "type": "git",