@maycombhq/sdk 2.0.0-beta.18 → 2.0.0-beta.21

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.
@@ -0,0 +1,29 @@
1
+ import { type DecisionBatchT } from "./ai-decisions.js";
2
+ /**
3
+ * ADR 0181: the batch records under `decisions/` (`.atticus/decisions/` when adopted), one file
4
+ * per batch, and the `corrections-v2` upgrade step. The lines a batch names stay in the repos'
5
+ * corrections files and the answers in the question files; the record is what Undo reads.
6
+ */
7
+ /** Where a batch's record is, relative to the root. */
8
+ export declare const batchRelOf: (root: string, id: string) => string;
9
+ /** Write a batch's record (a new one, or the same one undone). */
10
+ export declare function writeBatch(root: string, b: DecisionBatchT): Promise<string>;
11
+ /** One batch's record; undefined when there is none (or the id isn't a batch's). */
12
+ export declare function readBatch(root: string, id: string): Promise<DecisionBatchT | undefined>;
13
+ /** Every batch on record, newest first, with the files that don't read as one. */
14
+ export declare function listBatches(root: string): Promise<{
15
+ batches: DecisionBatchT[];
16
+ problems: {
17
+ file: string;
18
+ message: string;
19
+ }[];
20
+ }>;
21
+ /**
22
+ * The `corrections-v2` step (ADR 0181): a corrections line that uses version 2's fields (an AI
23
+ * pairing, a batch, a rule, a match, an unlink) but says version 1, as a hand edit might, says 2;
24
+ * every other line means the same at version 1 and is left exactly as it is. Returns the files,
25
+ * relative to the root; with dryRun, the files it would rewrite.
26
+ */
27
+ export declare function migrateCorrections(root: string, o?: {
28
+ dryRun?: boolean;
29
+ }): Promise<string[]>;
@@ -0,0 +1,62 @@
1
+ import { type LineChange } from "./manifest-edit.js";
2
+ /**
3
+ * G3 (ADR 0174): what a person declares on the canvas that the code can't show, written to the
4
+ * profile that has the system, comments and order kept, for review. A topic the system publishes
5
+ * or listens on goes under its `topics` (ADR 0162: a publish or listener of the estate with no
6
+ * counterpart lands on it, marked declared); a call it makes to a gateway route goes under its
7
+ * `calls` (A-callers). Who declared it and when is the line's comment. Nothing here is a fact.
8
+ */
9
+ export type Declared = {
10
+ kind: "topic";
11
+ system: string;
12
+ topic: string;
13
+ side: "publishes" | "listens";
14
+ } | {
15
+ kind: "call";
16
+ system: string;
17
+ route: string;
18
+ };
19
+ export interface DeclaredOnFile {
20
+ kind: "topic" | "call";
21
+ system: string;
22
+ /** The topic, or the route. */
23
+ value: string;
24
+ /** publishes or listens, for a topic declared from the canvas. */
25
+ side?: "publishes" | "listens";
26
+ /** Who declared it and when, from its comment; none for a line a person wrote by hand. */
27
+ by?: string;
28
+ at?: string;
29
+ }
30
+ export declare class DeclareError extends Error {
31
+ readonly code: "not-found" | "invalid" | "exists";
32
+ constructor(code: "not-found" | "invalid" | "exists", message: string);
33
+ }
34
+ /** The comment a declaration carries: which side, who and when. */
35
+ export declare const declaredComment: (by: string, at: string, side?: "publishes" | "listens") => string;
36
+ /**
37
+ * Write a declaration (or, with `preview`, say the lines it changes). The profile moves to
38
+ * version 2 when a topic needs it; the whole profile is checked before it is written.
39
+ */
40
+ export declare function declareLink(root: string, d: Declared, o: {
41
+ by: string;
42
+ at: string;
43
+ preview?: boolean;
44
+ }): Promise<{
45
+ rel: string;
46
+ changes: LineChange[];
47
+ written: boolean;
48
+ }>;
49
+ /** Undo: remove a declared topic or call from the system's list, exactly that one. */
50
+ export declare function undeclareLink(root: string, d: {
51
+ kind: "topic" | "call";
52
+ system: string;
53
+ value: string;
54
+ }): Promise<{
55
+ rel: string;
56
+ changes: LineChange[];
57
+ }>;
58
+ /** A system's declarations, with who and when where the canvas wrote them. */
59
+ export declare function declaredOf(root: string, system: string): Promise<{
60
+ rel?: string;
61
+ list: DeclaredOnFile[];
62
+ }>;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * A file rewritten keeps its line endings: a Windows file's CRLF stays CRLF (where Git doesn't
3
+ * normalise them, the whole file would otherwise show as changed in the upgrade's pull request).
4
+ */
5
+ export declare function keepLineEndings(was: string, now: string): string;
@@ -195,6 +195,14 @@ export declare const JOINED_DESPITE_CONFLICT = "joined-despite-conflict";
195
195
  * `<name>.<namespace>` and the whole `<name>.<namespace>.svc[.cluster.local]` address are no guess.
196
196
  */
197
197
  export declare const JOINED_BY_SERVICE_NAME = "joined-by-service-name";
198
+ /** G1 (ADR 0174): a person paired the call with this entry on the canvas. */
199
+ export declare const JOINED_BY_PERSON = "joined-by-person";
200
+ /**
201
+ * ADR 0181: the AI decided the link (a pairing, or a target answer), applied by Atticus from its
202
+ * run without a person. A how, never a person's word: the Interface is inferred, its evidence is
203
+ * `source: ai` with the run, and plans and checks tell it from a person's.
204
+ */
205
+ export declare const JOINED_BY_AI = "joined-by-ai";
198
206
  /** The guesses of J0 and J1 a join by host can carry (`FactJoin.guesses`). */
199
207
  export type JoinHostGuess = typeof JOINED_BY_PLATFORM_SETTING | typeof JOINED_BY_FOLDER_NAME | typeof JOINED_DESPITE_CONFLICT | typeof JOINED_BY_SERVICE_NAME;
200
208
  /**
@@ -275,6 +283,32 @@ export interface FactJoin {
275
283
  path: string;
276
284
  /** The catalog Interface of the join. */
277
285
  interface: string;
286
+ /**
287
+ * G1 (ADR 0174): a person paired the call with this entry; who did. ADR 0181: `ai` when the
288
+ * pairing is the AI's (written by Atticus from that run), never a person's word. `call` is set
289
+ * when the pairing was a gateway hop's forwarding call (the line the person's evidence cites):
290
+ * a hop a person paired makes the whole walked link that person's pairing.
291
+ */
292
+ paired?: {
293
+ by: string;
294
+ ai?: JoinAi;
295
+ call?: FactEnd;
296
+ };
297
+ /** ADR 0181: the target answer that joined it was the AI's, from that run. */
298
+ aiAnswer?: JoinAi;
299
+ /**
300
+ * ADR 0181 (ninth UX walk): a gateway hop on the way (`gateway`) was joined by the AI (its
301
+ * forwarding call's pairing or target answer), so the whole link is the AI's: `call` is that
302
+ * hop's forwarding call, the line the AI's evidence cites.
303
+ */
304
+ aiHop?: JoinAi & {
305
+ call: FactEnd;
306
+ };
307
+ }
308
+ /** ADR 0181: the AI run a decision came from. */
309
+ export interface JoinAi {
310
+ runtime: string;
311
+ run: string;
278
312
  }
279
313
  export interface FactJoinAsk {
280
314
  call: FactEnd;
@@ -385,10 +419,34 @@ export interface FactsJoinResult {
385
419
  /** With `explain`: every call left, with why; left out otherwise. */
386
420
  left?: FactJoinLeft[];
387
421
  }
422
+ /**
423
+ * G1 (ADR 0174): a person paired a call with an API of another box on the canvas: the entry of a
424
+ * repo it reaches (by id, else by method and path when a read gave it another id), or an outside
425
+ * system's operation. Written as a `link` line in the caller's corrections file.
426
+ */
427
+ export interface PersonPair {
428
+ /** The repo whose entry the call reaches; or `system` for an outside system. */
429
+ repo?: string;
430
+ system?: string;
431
+ /** The entry's fact id when it was paired. */
432
+ entry?: string;
433
+ method?: string;
434
+ path: string;
435
+ by: string;
436
+ /** ADR 0181: the pairing is the AI's, with its run; joined `joined-by-ai`. */
437
+ ai?: JoinAi;
438
+ }
388
439
  export interface JoinFactsInput {
389
440
  repos: readonly JoinRepo[];
390
441
  /** A person's answer naming the repo or component a call goes to: repo → call fact id → name. */
391
442
  targets?: Readonly<Record<string, Readonly<Record<string, string>>>>;
443
+ /**
444
+ * ADR 0181: of `targets`, those the AI answered (repo → call fact id → its run): joined
445
+ * `joined-by-ai`, never `joined-by-answer`, so no reader takes them as a person's word.
446
+ */
447
+ aiTargets?: Readonly<Record<string, Readonly<Record<string, JoinAi>>>>;
448
+ /** G1: a person's pairings, caller repo → call fact id → what it reaches. They outrank answers. */
449
+ pairs?: Readonly<Record<string, Readonly<Record<string, PersonPair>>>>;
392
450
  /**
393
451
  * Outside systems (the org pack's vendors), by id: a call whose `to` names one keeps it and
394
452
  * is never joined by path to an entry of the estate.
@@ -492,7 +550,14 @@ export declare const isGuessedJoin: (j: Pick<FactJoin, "inferred" | "byLabel" |
492
550
  * J0; despite a conflict or by a Service's short name, J1), any other by how it was made
493
551
  * (`joined-by-answer`, `-name`, `-repo`, `-host`); a publish joined to its listener has none.
494
552
  */
495
- export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses">): string[];
553
+ /** ADR 0181: the AI run behind a join's own pairing or target answer, if the AI made it. */
554
+ export declare const aiOfJoin: (j: Pick<FactJoin, "how" | "paired"> & {
555
+ aiAnswer?: JoinAi | undefined;
556
+ }) => JoinAi | undefined;
557
+ export declare function joinFlagsOf(j: Pick<FactJoin, "how" | "inferred" | "byLabel" | "guesses" | "paired"> & {
558
+ aiAnswer?: JoinAi | undefined;
559
+ aiHop?: JoinAi | undefined;
560
+ }): string[];
496
561
  /**
497
562
  * A shared link's flags (ADR 0135, section 5): each once, the union of its joins'. A verified link
498
563
  * lists how its cited joins were made first, then the guesses its other calls rest on; an
package/npm/core/fs.d.ts CHANGED
@@ -6,6 +6,17 @@
6
6
  * it is retried a few times before giving up.
7
7
  */
8
8
  export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
9
+ /** A file changed on disk between being read and being written back: nothing was written. */
10
+ export declare class FileChangedError extends Error {
11
+ readonly path: string;
12
+ constructor(path: string);
13
+ }
14
+ /**
15
+ * Write a file back only when it still holds what the change was made from (`before`, the text
16
+ * as read; undefined when it wasn't there), so an edit made meanwhile (another request, the CLI,
17
+ * an editor) is never overwritten: that throws FileChangedError instead.
18
+ */
19
+ export declare function writeFileIfUnchanged(path: string, before: string | undefined, data: string): Promise<void>;
9
20
  export declare function renameRetrying(from: string, to: string, tries?: number): Promise<void>;
10
21
  export interface LockInfo {
11
22
  pid: number;
@@ -15,12 +26,16 @@ export interface LockInfo {
15
26
  }
16
27
  export declare class LockHeldError extends Error {
17
28
  readonly held: LockInfo;
18
- constructor(held: LockInfo);
29
+ readonly file?: string | undefined;
30
+ constructor(held: LockInfo, file?: string | undefined);
19
31
  }
20
32
  /** Where a metarepo's locks live: .atticus/locks/, on this machine only (git-ignored). */
21
33
  export declare const lockFileOf: (root: string, name: string) => string;
22
34
  /** Read a lock: undefined when free; `stale` when its process is gone (it was cut short). */
23
- export declare function readLock(root: string, name: string): Promise<(LockInfo & {
35
+ export declare function readLock(root: string, name: string, o?: {
36
+ maxAgeMs?: number;
37
+ now?: () => Date;
38
+ }): Promise<(LockInfo & {
24
39
  stale: boolean;
25
40
  }) | undefined>;
26
41
  /**
@@ -28,7 +43,11 @@ export declare function readLock(root: string, name: string): Promise<(LockInfo
28
43
  * gone was cut short (a crash, a closed terminal); it is taken over and reported as
29
44
  * `interrupted`, so the caller can say the last run didn't finish.
30
45
  */
31
- export declare function acquireLock(root: string, name: string, what: string, now?: () => Date): Promise<{
46
+ export declare function acquireLock(root: string, name: string, what: string, now?: () => Date,
47
+ /** A lock older than this is taken over (Windows reuses a dead process's PID). */
48
+ o?: {
49
+ maxAgeMs?: number;
50
+ }): Promise<{
32
51
  release: () => Promise<void>;
33
52
  interrupted?: LockInfo;
34
53
  }>;
@@ -1,3 +1,4 @@
1
+ import { type LineChange } from "./manifest-edit.js";
1
2
  /**
2
3
  * Which repo answers on a host (ADR 0088): a scan or atticus estate join asks, as a question
3
4
  * file (ADR 0078), for each host the estate's calls name that no repo lists in its `hosts`;
@@ -87,11 +88,15 @@ export declare function addProfileSystem(root: string, repo: string, s: {
87
88
  * `aliases`, with the profile at schema version 2.
88
89
  */
89
90
  topics?: string[];
91
+ }, o?: {
92
+ preview?: boolean;
90
93
  }): Promise<{
91
94
  id: string;
92
95
  profile: string;
93
96
  added: boolean;
94
97
  topics?: string[];
98
+ /** The lines a new system changes in the profile (as the write makes them). */
99
+ changes?: LineChange[];
95
100
  }>;
96
101
  /**
97
102
  * Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
@@ -31,6 +31,7 @@ export * from "./schema/frameworks.js";
31
31
  export * from "./schema/scan-settings.js";
32
32
  export * from "./schema/scan-verify.js";
33
33
  export * from "./schema/repo-type.js";
34
+ export * from "./schema/component-type.js";
34
35
  export * from "./schema/layout.js";
35
36
  export * from "./schema/plugin.js";
36
37
  export * from "./schema/review.js";
@@ -68,6 +69,7 @@ export * from "./host-questions.js";
68
69
  export * from "./repo-reads.js";
69
70
  export * from "./question-order.js";
70
71
  export * from "./question-owners.js";
72
+ export * from "./question-roles.js";
71
73
  export * from "./question-proposals.js";
72
74
  export * from "./repo-description.js";
73
75
  export * from "./manifest-edit.js";
@@ -75,3 +77,8 @@ export * from "./schema/spec.js";
75
77
  export * from "./specs.js";
76
78
  export * from "./cancel.js";
77
79
  export * from "./assistant-actor.js";
80
+ export * from "./link-candidates.js";
81
+ export * from "./ai-decisions.js";
82
+ export * from "./decision-batches.js";
83
+ export * from "./declared-links.js";
84
+ export * from "./schema/reading-rules.js";
@@ -0,0 +1,103 @@
1
+ import type { FactsJoinResult, PersonPair } from "./facts-join.js";
2
+ import type { Fact } from "./schema/facts.js";
3
+ /**
4
+ * G1 (ADR 0174): connect two boxes call by call. Box A's calls that join nothing (asked,
5
+ * unresolved, missed, left), box B's APIs (a service's entries, a proxy's routes, an outside
6
+ * system's operations from its intaken spec), and for each call the API it most likely is.
7
+ * Pure: the caller reads the facts, the join and the spec.
8
+ */
9
+ export type LooseStatus = "asked" | "missed" | "left" | "outside" | "unresolved"
10
+ /** Already paired by a person with an API of this box. */
11
+ | "paired";
12
+ export interface CandidateApi {
13
+ /** The entry's fact id, or the operation's id in the spec. */
14
+ id: string;
15
+ kind: "entry" | "route" | "operation";
16
+ method?: string;
17
+ path: string;
18
+ /** file:line, for an entry. */
19
+ at?: string;
20
+ /** Words that name it besides its path: a spec operation's operationId, a route's name. */
21
+ words?: string;
22
+ /** A gateway route: the path it forwards to (what the service behind it serves). */
23
+ forwards?: string;
24
+ }
25
+ export interface CandidateCall {
26
+ fact: string;
27
+ callType: string;
28
+ method?: string;
29
+ path: string;
30
+ at: string;
31
+ status: LooseStatus;
32
+ /** What the join said: the reason it left it, the target it missed, the host it asked about. */
33
+ why?: string;
34
+ /** For paired: the API it is paired with. */
35
+ paired?: string;
36
+ suggestion?: {
37
+ api: string;
38
+ score: number;
39
+ why: SuggestWhy;
40
+ };
41
+ /** The APIs it most likely is, best first (at most three); the first is `suggestion`. */
42
+ suggestions?: {
43
+ api: string;
44
+ score: number;
45
+ why: SuggestWhy;
46
+ }[];
47
+ /** The best is well ahead of the rest and scores high: safe to pair without a look. */
48
+ confident?: boolean;
49
+ }
50
+ export type SuggestWhy = "same-path" | "prefix" | "parameter" | "names-alike"
51
+ /** The call's path, with its settings resolved, is the API's. */
52
+ | "setting"
53
+ /** The call's words match the operation's name (operationId) or the route's. */
54
+ | "operation-words"
55
+ /** The call's path is what the gateway's route forwards to. */
56
+ | "forwarded-path";
57
+ export interface LinkCandidates {
58
+ calls: CandidateCall[];
59
+ apis: CandidateApi[];
60
+ }
61
+ /** A call's path with the settings it names filled in (`${api.base}/x` → `/v2/x`). */
62
+ export declare function resolvePath(p: string, settings: Readonly<Record<string, string>> | undefined): {
63
+ path: string;
64
+ resolved: boolean;
65
+ };
66
+ /** The words of a path or of a name that holds one (`requestRefundPath`), lower case. */
67
+ export declare function wordsOf(p: string): Set<string>;
68
+ /**
69
+ * How likely a call is the API: 0 to 1, and why. The best of: the paths as written, the call's
70
+ * path with its settings resolved, the path the API's route forwards to, and the words.
71
+ */
72
+ export declare function pairScore(call: {
73
+ method?: string;
74
+ path: string;
75
+ }, api: {
76
+ method?: string;
77
+ path: string;
78
+ words?: string;
79
+ forwards?: string;
80
+ }, settings?: Readonly<Record<string, string>>): {
81
+ score: number;
82
+ why: SuggestWhy;
83
+ } | undefined;
84
+ /** The suggestion threshold: below it, a call gets none. */
85
+ export declare const SUGGEST_AT = 0.35;
86
+ /** A suggestion this sure, and this far ahead of the next, is confident: safe to pair unseen. */
87
+ export declare const CONFIDENT_AT = 0.85;
88
+ export declare const CONFIDENT_LEAD = 0.2;
89
+ export declare function linkCandidates(o: {
90
+ from: string;
91
+ facts: readonly Fact[];
92
+ join: Pick<FactsJoinResult, "joins" | "asks" | "misses" | "outside" | "left">;
93
+ apis: readonly CandidateApi[];
94
+ /** The pairings of `from` already on file, and the box they are with. */
95
+ pairs?: Readonly<Record<string, PersonPair>>;
96
+ /** The box B: a repo or an outside system id. */
97
+ to: {
98
+ repo?: string;
99
+ system?: string;
100
+ };
101
+ /** A's settings by key (its config facts with a value), to fill a call's `${key}` in. */
102
+ settings?: Readonly<Record<string, string>>;
103
+ }): LinkCandidates;
@@ -55,3 +55,43 @@ export declare function migrateManifests(root: string, o?: {
55
55
  dryRun?: boolean;
56
56
  to?: number;
57
57
  }): Promise<string[]>;
58
+ /** A file's line ending, its text with LF only, and the text back in its own endings. */
59
+ export declare const eolOf: (raw: string) => "\r\n" | "\n";
60
+ export declare const lfOnly: (raw: string) => string;
61
+ export declare const inEol: (text: string, eol: "\r\n" | "\n") => string;
62
+ /** A line the edit changes: what it was (none when added) and what it is now. */
63
+ export interface LineChange {
64
+ was?: string;
65
+ now?: string;
66
+ }
67
+ /**
68
+ * The lines two texts differ in, in order: a line diff (longest common subsequence), each run of
69
+ * removed and added lines paired up as was and now. For a preview of a file's change.
70
+ */
71
+ export declare function changedLines(before: string, after: string): LineChange[];
72
+ /**
73
+ * G2 (ADR 0174): set a repo's `owner` or `system` in the manifest that lists it, keeping the
74
+ * file's comments and order; checked before it is written. With `preview`, nothing is written:
75
+ * the lines it would change come back.
76
+ */
77
+ export declare function setManifestField(root: string, repo: string, field: "owner" | "system", value: string, o?: {
78
+ preview?: boolean;
79
+ }): Promise<{
80
+ file: ManifestFile;
81
+ changes: LineChange[];
82
+ written: boolean;
83
+ }>;
84
+ /**
85
+ * G2 (ADR 0174): add a team to roles.yaml (moved to version 2 first when it is older), for
86
+ * review: its id and name, no people. With `preview`, nothing is written.
87
+ */
88
+ export declare function addRolesTeam(root: string, team: {
89
+ id: string;
90
+ name: string;
91
+ }, o?: {
92
+ preview?: boolean;
93
+ }): Promise<{
94
+ rel: string;
95
+ changes: LineChange[];
96
+ written: boolean;
97
+ }>;
@@ -21,6 +21,12 @@ export interface MergeRepo {
21
21
  type: string;
22
22
  /** Hosts the repo's component (or, for a gateway repo, the gateway) answers on (ADR 0053). */
23
23
  hosts?: string[];
24
+ /**
25
+ * beta.18: the repo's facts are read, so its endpoints are known: a call to one of its hosts
26
+ * joins it only where one of them serves the call (the facts join's own rule). Unset, as
27
+ * before: a host the manifest lists joins every call to it.
28
+ */
29
+ read?: boolean;
24
30
  }
25
31
  export interface MergeSystem {
26
32
  id: string;
@@ -51,6 +57,12 @@ export interface MergePattern {
51
57
  export declare const DECLARED_TOPIC = "declared-topic";
52
58
  export interface MergeInput {
53
59
  records: CatalogRecord[];
60
+ /**
61
+ * The component type ids the organisation has (ADR 0180: the built-ins with the org pack's
62
+ * applied). A Component's type that is one of these is never replaced by a repo type from the
63
+ * manifest. Left out, Atticus's documented types (ADR 0040).
64
+ */
65
+ componentTypes?: ReadonlySet<string>;
54
66
  repos: MergeRepo[];
55
67
  systems: MergeSystem[];
56
68
  patterns?: MergePattern[];
@@ -80,6 +92,13 @@ export interface MergeResult {
80
92
  }
81
93
  /** A record id cut to fit: its start, then a hash of the whole id, the same for the same id. */
82
94
  export declare const fitRecordId: (id: string) => string;
95
+ /**
96
+ * A plural noun's singular, by plain English rules (one for endpoint ids and the glossary):
97
+ * "transfers" → "transfer", "policies" → "policy", "addresses" → "address", "statuses" →
98
+ * "status", "aliases" → "alias"; "status", "analysis" and "access" stay as they are; "causes",
99
+ * "excuses", "cases" and "responses" lose only their s.
100
+ */
101
+ export declare function singularNoun(word: string): string;
83
102
  /** Canonical REST endpoint id: <component>.<method>-<last fixed path segment, singular>. */
84
103
  export declare function endpointId(component: string, method: string | undefined, normalizedPath: string): string;
85
104
  export declare function mergeCatalog(input: MergeInput): MergeResult;
@@ -16,6 +16,13 @@ export declare function inputsDirOf(root: string): string;
16
16
  export declare function proposalsRelOf(root: string): string;
17
17
  /** The proposals folder: `proposals/`, or `.atticus/proposals/` when adopted. */
18
18
  export declare function proposalsDirOf(root: string): string;
19
+ /**
20
+ * ADR 0181: the record of each batch of decisions applied at once (by the AI, or by a person's
21
+ * rule), so Undo removes exactly its lines: `decisions/<batch id>.yaml`, or under `.atticus/`.
22
+ */
23
+ export declare function decisionsRelOf(root: string): string;
24
+ /** The decisions folder (ADR 0181). */
25
+ export declare function decisionsDirOf(root: string): string;
19
26
  /** Where questions to people live (ADR 0078), relative to the root: `questions`, or `.atticus/questions` when adopted. */
20
27
  export declare function questionsRelOf(root: string): string;
21
28
  /** The questions folder (ADR 0078). */
@@ -24,6 +31,8 @@ export declare function questionsDirOf(root: string): string;
24
31
  export declare function factsRelOf(root: string): string;
25
32
  /** The facts folder (ADR 0124): `<repo>.jsonl` the assistant writes, `<repo>.rejected.jsonl` and `<repo>.verify.yaml` the verifier writes. */
26
33
  export declare function factsDirOf(root: string): string;
34
+ /** The diagrams folder (kept arrangements and views, ADR 0081, 0175), relative to the root: `diagrams`, or `.atticus/diagrams` when adopted. */
35
+ export declare function diagramsRelOf(root: string): string;
27
36
  /** Where evidence from outside the code lives (ADR 0151), relative to the root: `evidence`, or `.atticus/evidence` when adopted. */
28
37
  export declare function evidenceRelOf(root: string): string;
29
38
  /** Where other teams' shared maps live (ADR 0160), relative to the root: `shared`, or `.atticus/shared` when adopted. */
@@ -5,7 +5,7 @@ export declare const DEFAULT_CHANGE_TYPES: {
5
5
  name: string;
6
6
  phases: ("release" | "design" | "qa" | "define" | "plan" | "build")[];
7
7
  artifacts: ("interfaces" | "data" | "ux" | "brief" | "proposal" | "specs" | "mappings" | "design" | "stories" | "tasks" | "snow")[];
8
- lenses: ("true" | "complete" | "safe" | "ship" | "business" | "architecture" | "story" | "ux" | "delivery" | "code-and-test" | "release")[];
8
+ lenses: ("release" | "true" | "complete" | "safe" | "ship" | "business" | "architecture" | "story" | "ux" | "delivery" | "code-and-test")[];
9
9
  approvals: Partial<Record<"release" | "design" | "qa" | "define" | "plan" | "build", string[]>>;
10
10
  postReleaseReview: boolean;
11
11
  description?: string | undefined;
@@ -57,7 +57,7 @@ export declare const DEFAULT_ROLES: {
57
57
  }[];
58
58
  };
59
59
  export declare const DEFAULT_RUNTIME: {
60
- schemaVersion: 1 | 2 | 3;
60
+ schemaVersion: 1 | 2 | 3 | 4;
61
61
  assistants: {
62
62
  allowed: ("copilot" | "claude-code" | "cursor" | "gemini-cli" | "windsurf" | "agents-md")[];
63
63
  default: "copilot" | "claude-code" | "cursor" | "gemini-cli" | "windsurf" | "agents-md";
@@ -139,6 +139,11 @@ export declare const DEFAULT_RUNTIME: {
139
139
  maxTurns?: number | undefined;
140
140
  timeoutMs?: number | undefined;
141
141
  } | undefined;
142
+ decide?: {
143
+ links: "auto" | "propose";
144
+ questions: "auto" | "propose";
145
+ minPrecision: number;
146
+ } | undefined;
142
147
  buildEngine?: {
143
148
  default: "atticus" | "speckit";
144
149
  perRepo: Record<string, "atticus" | "speckit">;
@@ -1,6 +1,7 @@
1
1
  import { FrameworkModel } from "./schema/frameworks.js";
2
2
  import { ScanSettings } from "./schema/scan-settings.js";
3
3
  import { RepoType } from "./schema/repo-type.js";
4
+ import { type LoadedComponentType } from "./schema/component-type.js";
4
5
  import { ModelProviderPlugin, ScannerPlugin } from "./schema/plugin.js";
5
6
  import { SpecTemplate } from "./schema/spec.js";
6
7
  import type { z } from "zod";
@@ -38,6 +39,8 @@ export interface OrgPack {
38
39
  scanSettings: ScanSettings[];
39
40
  /** Repo types (ADR 0077), from repo-types/<id>/type.yaml. */
40
41
  repoTypes: RepoType[];
42
+ /** The organisation's component types (ADR 0180), from component-types/<id>/type.yaml, with their notes.md. */
43
+ componentTypes: LoadedComponentType[];
41
44
  /** Scanner plugins (ADR 0080), from plugins/<id>/plugin.yaml, with their folders. */
42
45
  plugins: {
43
46
  manifest: ScannerPlugin;
@@ -0,0 +1,24 @@
1
+ import { BUILT_IN_ROLES } from "./schema/orgpack.js";
2
+ import { type Question, type QuestionRole } from "./schema/question.js";
3
+ /**
4
+ * The role that owns what a step asks: the stage's own for a change's stage (`change-feature`,
5
+ * `change-stories`, a task's run), else, for a step that serves every stage (a context gap, a
6
+ * knowledge conflict), the stage its rerun command names. Undefined outside a change's phases.
7
+ */
8
+ export declare function roleOfStep(step: string, rerun?: string): QuestionRole | undefined;
9
+ /** A question's role: its own (version 5), else derived from the step that asked and its rerun. */
10
+ export declare function roleOfQuestion(q: Pick<Question, "askedBy" | "rerun"> & {
11
+ role?: QuestionRole | undefined;
12
+ }): QuestionRole | undefined;
13
+ /** A custom role of roles.yaml (`custom`): its id and the built-in role it is based on. */
14
+ export interface CustomRole {
15
+ id: string;
16
+ basedOn: (typeof BUILT_IN_ROLES)[number] | string;
17
+ }
18
+ /** The question role of an owner key in change.yaml (`architect`, or a custom role of roles.yaml). */
19
+ export declare function roleOfOwner(key: string, custom?: readonly CustomRole[]): QuestionRole | undefined;
20
+ /**
21
+ * The roles a person has on a change: every owner key of its change.yaml that names them, as a
22
+ * question role, once each, in the order of the phases.
23
+ */
24
+ export declare function rolesOfPerson(handle: string, owners: Readonly<Record<string, readonly string[]>>, custom?: readonly CustomRole[]): QuestionRole[];
@@ -1,5 +1,5 @@
1
1
  import { type JudgmentStore } from "./judgments.js";
2
- import { Question, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
2
+ import { Question, type AiBy, type AppliedRule, type QuestionDraft, type QuestionScopeLevel, type QuestionState } from "./schema/question.js";
3
3
  /**
4
4
  * Questions as files (ADR 0078): raise, list, read and answer questions/<id>.yaml. The CLI
5
5
  * (atticus questions) and the local API (/api/questions) both call these, so the app and the
@@ -21,6 +21,21 @@ export declare function questionId(o: {
21
21
  question: string;
22
22
  evidence: string[];
23
23
  }): string;
24
+ /** The step a critic knowledge gap's owner question is asked by (ninth UX walk). */
25
+ export declare const ASKED_GAP_STEP = "critic-ask";
26
+ /**
27
+ * Ninth UX walk: the id of the owner question a person's Ask raises for a critic knowledge gap.
28
+ * It is a fingerprint of the change and the gap's own fingerprint (its rule, artifact, record and
29
+ * summary), so the same gap carried to a later round or gate finds the same question.
30
+ */
31
+ export declare function askedGapQuestionId(change: string, f: {
32
+ rule: string;
33
+ artifact: string;
34
+ locator: {
35
+ record?: string | undefined;
36
+ };
37
+ summary: string;
38
+ }): string;
24
39
  /** Who asked: the step, the repo, the command as typed, the command that reads the answer. */
25
40
  export interface AskedBy {
26
41
  step: string;
@@ -277,8 +292,16 @@ export interface AnswerInput {
277
292
  * nothing is answered (a `bad-answer` with its first line).
278
293
  */
279
294
  beforeWrite?: () => Promise<void>;
280
- by: string;
295
+ /**
296
+ * The person (their Git user); or, ADR 0181, the AI with its runtime and run, for a decision
297
+ * Atticus applies from an AI run (only an option on file, of a targets question, at the repo).
298
+ */
299
+ by: string | AiBy;
281
300
  at: string;
301
+ /** ADR 0181: the batch applying it (by AI, or by a person's rule). */
302
+ batch?: string;
303
+ /** ADR 0181: a person's rule applies it, from their correction. */
304
+ rule?: AppliedRule;
282
305
  }
283
306
  /**
284
307
  * Whether a host a hosts question asks about (`localhost:9966`, `limits.payments.forge.internal`)
@@ -18,3 +18,12 @@ export declare function migrateRuntimeV3Text(text: string): {
18
18
  text: string;
19
19
  changed: boolean;
20
20
  };
21
+ /**
22
+ * runtime.yaml to version 4 (ADR 0181), for a file that sets `decide` (whether the AI decides
23
+ * pairings and option questions itself): the number only, every other line as the person wrote
24
+ * it. A file without it means the same at version 1 to 3, so it is left as it is.
25
+ */
26
+ export declare function migrateRuntimeV4Text(text: string): {
27
+ text: string;
28
+ changed: boolean;
29
+ };