@fro.bot/systematic 3.23.0 → 3.24.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.
@@ -3,7 +3,7 @@ declare const CAPABILITY_SNAPSHOT_SCHEMA_VERSION: 'cli-capabilities.v1';
3
3
  declare const CAPABILITY_SNAPSHOT_COMMAND: 'systematic capabilities';
4
4
  declare const CAPABILITY_SOURCE_IDS: readonly ['config:custom', 'config:global', 'config:project', 'config:user', 'discovery:agents', 'discovery:skills', 'host:runtime', 'package'];
5
5
  declare const CONFIG_SOURCE_KINDS: readonly ['custom', 'project', 'user'];
6
- declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands', 'workflow_guard.debug', 'workflow_guard.mode'];
6
+ declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands'];
7
7
  declare const CONFIG_SOURCE_ERROR_CODES: readonly ['parse-failed', 'read-failed', 'schema-invalid', 'source-invalid'];
8
8
  declare const CAPABILITY_SOURCE_PRESENCE: readonly ['absent', 'invalid', 'present'];
9
9
  declare const CAPABILITY_STATUSES: readonly ['available', 'unknown', 'unavailable'];
@@ -18,5 +18,5 @@
18
18
  * reason it exists as a separate file rather than living directly in
19
19
  * `config.ts`.
20
20
  */
21
- export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['workflow_guard', 'profiles', 'allow_project_profiles', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
21
+ export declare const CONFIG_PROTECTED_FIELD_PATHS: readonly ['profiles', 'allow_project_profiles', 'agents.*.model', 'agents.*.permission', 'agents.*.skills', 'agents.*.variant', 'agents.*.opencode', 'agents.*.pi', 'categories.*.model', 'categories.*.permission', 'categories.*.skills', 'categories.*.variant', 'categories.*.opencode', 'categories.*.pi'];
22
22
  export type ConfigProtectedFieldPath = (typeof CONFIG_PROTECTED_FIELD_PATHS)[number];
@@ -14,14 +14,6 @@
14
14
  * but is not reflected in the type declarations for this Zod 4 minor.
15
15
  */
16
16
  import { z } from 'zod';
17
- export declare const WorkflowGuardSchema: z.ZodDefault<z.ZodObject<{
18
- mode: z.ZodDefault<z.ZodEnum<{
19
- disabled: "disabled";
20
- observe: "observe";
21
- protected: "protected";
22
- }>>;
23
- debug: z.ZodDefault<z.ZodBoolean>;
24
- }, z.core.$strict>>;
25
17
  export declare const AgentOverlaySchema: z.ZodObject<{
26
18
  model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
27
19
  variant: z.ZodOptional<z.ZodString>;
@@ -404,14 +396,7 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
404
396
  enabled: z.ZodDefault<z.ZodBoolean>;
405
397
  file: z.ZodOptional<z.ZodString>;
406
398
  }, z.core.$strict>>;
407
- workflow_guard: z.ZodDefault<z.ZodObject<{
408
- mode: z.ZodDefault<z.ZodEnum<{
409
- disabled: "disabled";
410
- observe: "observe";
411
- protected: "protected";
412
- }>>;
413
- debug: z.ZodDefault<z.ZodBoolean>;
414
- }, z.core.$strict>>;
399
+ workflow_guard: z.ZodOptional<z.ZodUnknown>;
415
400
  pi_subagents: z.ZodDefault<z.ZodObject<{
416
401
  categories: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
417
402
  thinking: z.ZodOptional<z.ZodEnum<{
@@ -606,14 +591,7 @@ export declare const SystematicConfigSchema: z.ZodObject<{
606
591
  enabled: z.ZodDefault<z.ZodBoolean>;
607
592
  file: z.ZodOptional<z.ZodString>;
608
593
  }, z.core.$strict>>;
609
- workflow_guard: z.ZodDefault<z.ZodObject<{
610
- mode: z.ZodDefault<z.ZodEnum<{
611
- disabled: "disabled";
612
- observe: "observe";
613
- protected: "protected";
614
- }>>;
615
- debug: z.ZodDefault<z.ZodBoolean>;
616
- }, z.core.$strict>>;
594
+ workflow_guard: z.ZodOptional<z.ZodUnknown>;
617
595
  pi_subagents: z.ZodDefault<z.ZodObject<{
618
596
  categories: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
619
597
  thinking: z.ZodOptional<z.ZodEnum<{
@@ -4,11 +4,6 @@ export interface BootstrapConfig {
4
4
  enabled: boolean;
5
5
  file?: string;
6
6
  }
7
- export type WorkflowGuardMode = 'observe' | 'protected' | 'disabled';
8
- export interface WorkflowGuardConfig {
9
- mode: WorkflowGuardMode;
10
- debug: boolean;
11
- }
12
7
  export type OverlayConfig = Record<string, unknown>;
13
8
  export type OverlayConfigMap = Record<string, OverlayConfig>;
14
9
  /**
@@ -74,7 +69,7 @@ export interface SourcedOverlayConfigMap {
74
69
  agents: Record<string, SourcedOverlayConfig>;
75
70
  categories: Record<string, SourcedOverlayConfig>;
76
71
  }
77
- export declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands', 'workflow_guard.debug', 'workflow_guard.mode'];
72
+ export declare const CONFIG_AUTHORITY_FIELD_PATHS: readonly ['bootstrap.enabled', 'bootstrap.file', 'skills_as_commands'];
78
73
  export { CONFIG_PROTECTED_FIELD_PATHS, type ConfigProtectedFieldPath };
79
74
  export type ConfigSourceKind = 'custom' | 'project' | 'user';
80
75
  export type ConfigSourcePresence = 'absent' | 'invalid' | 'present';
@@ -172,7 +167,6 @@ export interface SystematicConfig {
172
167
  disabled_agents: string[];
173
168
  disabled_commands: string[];
174
169
  bootstrap: BootstrapConfig;
175
- workflow_guard: WorkflowGuardConfig;
176
170
  agents?: OverlayConfigMap;
177
171
  categories?: OverlayConfigMap;
178
172
  pi_subagents?: PiSubagentsOverlayMap;
@@ -14,3 +14,13 @@
14
14
  export declare const REMOVED_BUNDLED_SKILL_NAMES: readonly string[];
15
15
  export declare const REMOVED_BUNDLED_AGENT_NAMES: readonly string[];
16
16
  export declare const REMOVED_BUNDLED_AGENT_CATEGORIES: readonly string[];
17
+ /**
18
+ * Known-removed top-level config keys.
19
+ *
20
+ * A key listed here is still accepted by the config schema, warned about once
21
+ * per file that carries it, and then ignored, so upgrading does not brick a
22
+ * config that still sets it. Any other unknown top-level key is still rejected
23
+ * by strict validation. Add a key here only when its feature is deleted, and
24
+ * keep the matching deprecated stub in `config-schema.ts`.
25
+ */
26
+ export declare const REMOVED_CONFIG_KEYS: readonly string[];
@@ -1,5 +1,7 @@
1
1
  import type { ToolDefinition } from '@opencode-ai/plugin';
2
2
  export { discoverSkillFiles } from './skill-resolver.js';
3
+ /** The registry key of the skill tool; the host reports it as the part's `tool`. */
4
+ export declare const SKILL_TOOL_NAME = "systematic_skill";
3
5
  export interface SkillOutputStore {
4
6
  put(sessionID: string, callID: string, output: string): void;
5
7
  take(sessionID: string, callID: string): string | undefined;
@@ -15,6 +17,14 @@ export declare function createSkillOutputStore(options?: SkillOutputStoreOptions
15
17
  export declare function restoreSkillOutput(store: SkillOutputStore, input: unknown, output: unknown, options: {
16
18
  userOutputLimitSet: boolean;
17
19
  }): void;
20
+ /**
21
+ * Clears the `compacted` flag of completed skill-tool results in a request the
22
+ * host is assembling, so the model receives the stored body and not the prune
23
+ * placeholder. Each part gets a fresh `state.time` without `compacted`, so a
24
+ * failure partway through leaves every part valid. The host rebuilds the
25
+ * request from storage each time, so nothing persists.
26
+ */
27
+ export declare function restoreCompactedSkillResults(output: unknown): void;
18
28
  export interface SkillToolOptions {
19
29
  bundledSkillsDir: string;
20
30
  disabledSkills: string[];
package/dist/pi.js CHANGED
@@ -9414,6 +9414,9 @@ var REMOVED_BUNDLED_AGENT_NAMES = [
9414
9414
  var REMOVED_BUNDLED_AGENT_CATEGORIES = [
9415
9415
  "docs"
9416
9416
  ];
9417
+ var REMOVED_CONFIG_KEYS = [
9418
+ "workflow_guard"
9419
+ ];
9417
9420
 
9418
9421
  // src/lib/config-schema.ts
9419
9422
  var permissionSettingSchema = _enum(["ask", "allow", "deny"]);
@@ -9447,23 +9450,9 @@ var modeSchema = _enum(["subagent", "primary", "all"]).meta({
9447
9450
  description: "Agent execution mode",
9448
9451
  examples: ["subagent", "primary", "all"]
9449
9452
  });
9450
- var workflowGuardModeSchema = _enum([
9451
- "observe",
9452
- "protected",
9453
- "disabled"
9454
- ]);
9455
- var WorkflowGuardSchema = object({
9456
- mode: workflowGuardModeSchema.default("disabled").meta({
9457
- description: "Workflow guard mode. The guard is off by default (`disabled`); set `observe` or `protected` to turn it on.",
9458
- examples: ["observe", "protected", "disabled"]
9459
- }),
9460
- debug: boolean2().default(false).meta({
9461
- description: "Enable workflow guard debugging",
9462
- examples: [false, true]
9463
- })
9464
- }).strict().default({ mode: "disabled", debug: false }).meta({
9465
- description: "Workflow guard configuration. The guard is off by default; `mode: observe` or `mode: protected` turns it on.",
9466
- examples: [{ mode: "observe", debug: false }]
9453
+ var removedWorkflowGuardSchema = unknown().optional().meta({
9454
+ description: "Removed. The workflow guard no longer exists, so this setting has no effect and is ignored. Delete it from your config to silence the warning it triggers.",
9455
+ deprecated: true
9467
9456
  });
9468
9457
  var colorSchema = union([
9469
9458
  _enum(OPENCODE_AGENT_COLOR_TOKENS),
@@ -9744,7 +9733,7 @@ function createSystematicConfigSchema(opts) {
9744
9733
  { enabled: false, file: ".opencode/custom-prompt.md" }
9745
9734
  ]
9746
9735
  }),
9747
- workflow_guard: WorkflowGuardSchema,
9736
+ workflow_guard: removedWorkflowGuardSchema,
9748
9737
  pi_subagents: PiSubagentsSchema,
9749
9738
  skills_as_commands: boolean2().default(true).meta({
9750
9739
  description: "Register skills discovered from user/project skill directories (OpenCode config and other agent-harness-standard locations) as slash commands. Default true.",
@@ -10009,9 +9998,7 @@ function collectWrittenLegacyPiSubagentsThinkingWarnings(piSubagentsOverlays) {
10009
9998
  var CONFIG_AUTHORITY_FIELD_PATHS = [
10010
9999
  "bootstrap.enabled",
10011
10000
  "bootstrap.file",
10012
- "skills_as_commands",
10013
- "workflow_guard.debug",
10014
- "workflow_guard.mode"
10001
+ "skills_as_commands"
10015
10002
  ];
10016
10003
  var DEFAULT_CONFIG = {
10017
10004
  disabled_skills: [],
@@ -10020,10 +10007,6 @@ var DEFAULT_CONFIG = {
10020
10007
  bootstrap: {
10021
10008
  enabled: true
10022
10009
  },
10023
- workflow_guard: {
10024
- mode: "disabled",
10025
- debug: false
10026
- },
10027
10010
  agents: {},
10028
10011
  categories: {},
10029
10012
  pi_subagents: { categories: {}, agents: {} },
@@ -10048,10 +10031,7 @@ var PROTECTED_OVERLAY_FIELD_PATHS = {
10048
10031
  pi: "categories.*.pi"
10049
10032
  }
10050
10033
  };
10051
- var PROJECT_ALWAYS_PROTECTED_FIELDS = new Set([
10052
- "workflow_guard",
10053
- "allow_project_profiles"
10054
- ]);
10034
+ var PROJECT_ALWAYS_PROTECTED_FIELDS = new Set(["allow_project_profiles"]);
10055
10035
  var MAX_DIAGNOSTIC_TEXT = 200;
10056
10036
  var MAX_STRIP_WARNINGS = 20;
10057
10037
  var DIAGNOSTIC_ELLIPSIS = "…";
@@ -10268,6 +10248,7 @@ function loadConfigSource(filePath, trust, invalidSource, warningSink, allowProj
10268
10248
  config,
10269
10249
  path: filePath,
10270
10250
  protectedFields,
10251
+ removedKeys: REMOVED_CONFIG_KEYS.filter((key) => Object.hasOwn(rawConfig, key)),
10271
10252
  trust
10272
10253
  }
10273
10254
  };
@@ -10316,13 +10297,6 @@ function collectProjectProtectedFields(rawConfig, trust, allowProjectProfiles) {
10316
10297
  if (trust !== "project")
10317
10298
  return [];
10318
10299
  return [
10319
- ...Object.hasOwn(rawConfig, "workflow_guard") ? [
10320
- {
10321
- fieldPath: "workflow_guard",
10322
- outcome: "blocked",
10323
- sourceKind: "project"
10324
- }
10325
- ] : [],
10326
10300
  ...!allowProjectProfiles && Object.hasOwn(rawConfig, "profiles") ? [
10327
10301
  {
10328
10302
  fieldPath: "profiles",
@@ -10528,13 +10502,12 @@ function createAliasStripTracker(warningSink, aliasedCustomConfigPath) {
10528
10502
  };
10529
10503
  }
10530
10504
  function isAliasNoticeEligible(input) {
10531
- return input.aliasedCustomConfigPath !== undefined && (input.bufferedCount > 0 || input.hasProtectedFields);
10505
+ return input.aliasedCustomConfigPath !== undefined && input.bufferedCount > 0;
10532
10506
  }
10533
10507
  function emitAliasFailureDiagnostics(input) {
10534
10508
  if (!isAliasNoticeEligible({
10535
10509
  aliasedCustomConfigPath: input.aliasedCustomConfigPath,
10536
- bufferedCount: input.buffered.length,
10537
- hasProtectedFields: input.hasProtectedFields
10510
+ bufferedCount: input.buffered.length
10538
10511
  })) {
10539
10512
  return;
10540
10513
  }
@@ -10546,8 +10519,7 @@ function emitAliasFailureDiagnostics(input) {
10546
10519
  function buildAliasSuccessNotice(input) {
10547
10520
  if (!isAliasNoticeEligible({
10548
10521
  aliasedCustomConfigPath: input.aliasedCustomConfigPath,
10549
- bufferedCount: input.bufferedCount,
10550
- hasProtectedFields: input.hasProtectedFields
10522
+ bufferedCount: input.bufferedCount
10551
10523
  }) || !(input.projectLoaded && input.customLoaded) || input.aliasedCustomConfigPath === undefined) {
10552
10524
  return;
10553
10525
  }
@@ -10555,9 +10527,22 @@ function buildAliasSuccessNotice(input) {
10555
10527
  const projectConfigPath = input.projectConfigPath;
10556
10528
  const warningSink = input.warningSink;
10557
10529
  return () => {
10558
- warningSink(`[systematic] project config (${sanitizeDiagnosticText(projectConfigPath)}) and custom config (${sanitizeDiagnosticText(aliasedCustomConfigPath)}) resolve to the same file; protected fields stripped from the project pass (security-overlay fields, \`profiles\`, \`workflow_guard\`) apply through the custom-trust pass instead.`);
10530
+ warningSink(`[systematic] project config (${sanitizeDiagnosticText(projectConfigPath)}) and custom config (${sanitizeDiagnosticText(aliasedCustomConfigPath)}) resolve to the same file; protected fields stripped from the project pass (security-overlay fields, \`profiles\`, \`allow_project_profiles\`) apply through the custom-trust pass instead.`);
10559
10531
  };
10560
10532
  }
10533
+ var REMOVED_SETTINGS_DOCS_URL = "https://fro.bot/systematic/reference/configuration#removed-settings";
10534
+ function warnRemovedKeys(sources, warningSink) {
10535
+ const reported = new Set;
10536
+ for (const source of sources) {
10537
+ for (const key of source.removedKeys) {
10538
+ const identity = `${source.canonicalPath}\x00${key}`;
10539
+ if (reported.has(identity))
10540
+ continue;
10541
+ reported.add(identity);
10542
+ warningSink(`[systematic] \`${key}\` in config (${sanitizeDiagnosticText(source.path)}) has been removed and is ignored. Delete it from that file to silence this warning. See ${REMOVED_SETTINGS_DOCS_URL} for details.`);
10543
+ }
10544
+ }
10545
+ }
10561
10546
  function loadUserAndCustomSources(paths, invalidSource, warningSink) {
10562
10547
  const user = loadConfigSource(paths.userConfig, "user", invalidSource, warningSink, false);
10563
10548
  const custom = paths.customConfig ? loadConfigSource(paths.customConfig, "custom", invalidSource, warningSink, false) : {
@@ -10597,7 +10582,6 @@ function loadConfigWithSources(projectDir, options) {
10597
10582
  aliasedCustomConfigPath,
10598
10583
  buffered: projectStrip.buffered,
10599
10584
  customLoaded: custom.source !== null,
10600
- hasProtectedFields: (projectSource?.protectedFields.length ?? 0) > 0,
10601
10585
  projectLoaded: project.source !== null,
10602
10586
  warningSink
10603
10587
  });
@@ -10605,12 +10589,12 @@ function loadConfigWithSources(projectDir, options) {
10605
10589
  aliasedCustomConfigPath,
10606
10590
  bufferedCount: projectStrip.buffered.length,
10607
10591
  customLoaded: custom.source !== null,
10608
- hasProtectedFields: (projectSource?.protectedFields.length ?? 0) > 0,
10609
10592
  projectConfigPath: paths.projectConfig,
10610
10593
  projectLoaded: project.source !== null,
10611
10594
  warningSink
10612
10595
  });
10613
10596
  const sources = [userSource, projectSource, customSource].filter((source) => source !== null);
10597
+ warnRemovedKeys(sources, warningSink);
10614
10598
  const userConfig = userSource?.config;
10615
10599
  const projectConfig = projectSource?.config;
10616
10600
  const customConfig = customSource?.config;
@@ -10660,11 +10644,6 @@ function loadConfigWithSources(projectDir, options) {
10660
10644
  ...projectConfig?.bootstrap,
10661
10645
  ...customConfig?.bootstrap
10662
10646
  },
10663
- workflow_guard: {
10664
- ...DEFAULT_CONFIG.workflow_guard,
10665
- ...userConfig?.workflow_guard,
10666
- ...customConfig?.workflow_guard
10667
- },
10668
10647
  agents: overlayValues(overlays.agents),
10669
10648
  categories: overlayValues(overlays.categories),
10670
10649
  pi_subagents: {
@@ -10720,9 +10699,7 @@ function buildConfigObservationMetadata(summary) {
10720
10699
  const fieldCandidates = {
10721
10700
  "bootstrap.enabled": ["custom", "project", "user"],
10722
10701
  "bootstrap.file": ["custom", "project", "user"],
10723
- skills_as_commands: ["custom", "project", "user"],
10724
- "workflow_guard.debug": ["custom", "user"],
10725
- "workflow_guard.mode": ["custom", "user"]
10702
+ skills_as_commands: ["custom", "project", "user"]
10726
10703
  };
10727
10704
  for (const fieldPath of CONFIG_AUTHORITY_FIELD_PATHS) {
10728
10705
  const authority = firstDefinedSource(fieldPath, fieldCandidates[fieldPath]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.23.0",
3
+ "version": "3.24.1",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -82,7 +82,7 @@
82
82
  },
83
83
  "peerDependencies": {
84
84
  "@opencode-ai/plugin": "^1.1.30",
85
- "@earendil-works/pi-coding-agent": "^0.83.0",
85
+ "@earendil-works/pi-coding-agent": "^0.99.0",
86
86
  "typebox": "^1.1.38"
87
87
  },
88
88
  "peerDependenciesMeta": {
@@ -98,15 +98,15 @@
98
98
  },
99
99
  "devDependencies": {
100
100
  "@biomejs/biome": "2.5.15",
101
- "@earendil-works/pi-coding-agent": "0.83.0",
102
- "@opencode-ai/plugin": "1.19.0",
103
- "@opencode-ai/sdk": "1.19.0",
101
+ "@earendil-works/pi-coding-agent": "0.99.2",
102
+ "@opencode-ai/plugin": "1.19.3",
103
+ "@opencode-ai/sdk": "1.19.3",
104
104
  "@semantic-release/exec": "7.1.0",
105
105
  "@tintinweb/pi-subagents": "0.14.3",
106
106
  "@types/bun": "latest",
107
107
  "@types/js-yaml": "4.0.9",
108
108
  "@types/node": "26.6.5",
109
- "agent-browser": "0.34.0",
109
+ "agent-browser": "0.39.1",
110
110
  "ajv": "8.20.0",
111
111
  "ajv-formats": "3.0.1",
112
112
  "conventional-changelog-conventionalcommits": "10.4.1",
@@ -114,18 +114,16 @@
114
114
  "rimraf": "6.1.3",
115
115
  "semantic-release": "25.0.9",
116
116
  "semantic-release-export-data": "1.2.0",
117
- "typebox": "1.3.37",
117
+ "typebox": "1.4.2",
118
118
  "typescript": "7.0.2"
119
119
  },
120
120
  "dependencies": {
121
121
  "js-yaml": "^4.3.2",
122
122
  "jsonc-parser": "^3.3.0",
123
- "tree-sitter-bash": "0.25.1",
124
- "web-tree-sitter": "0.27.1",
125
123
  "zod": "4.6.7"
126
124
  },
127
125
  "overrides": {
128
- "@earendil-works/pi-ai": "0.83.0",
126
+ "@earendil-works/pi-ai": "0.99.2",
129
127
  "brace-expansion": "^5.0.8",
130
128
  "conventional-changelog-writer": ">=9",
131
129
  "devalue": "^5.9.3",
@@ -31,6 +31,7 @@ agent-browser skills get slack # Slack workspace automation
31
31
  agent-browser skills get dogfood # Exploratory testing / QA / bug hunts
32
32
  agent-browser skills get derive-client # Record a HAR, derive a standalone API client for a site
33
33
  agent-browser skills get vercel-sandbox # agent-browser inside Vercel Sandbox microVMs
34
+ agent-browser skills get protected-vercel-deployments # Access protected Vercel deployments
34
35
  agent-browser skills get agentcore # AWS Bedrock AgentCore cloud browsers
35
36
  ```
36
37
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  Choose the template matching the problem_type track (see `references/schema.yaml`).
4
4
 
5
+ **Citing code:** write a repo-relative path with the line or range (`<file>:<line>` or `<file>:<start>-<end>`), never a bare file name, and put the backticked symbol it points at in the same sentence. Link a tag or commit for code outside the repo or deleted code. Write placeholders such as `<file>:<line>` in examples. The content-integrity gate checks citations in `docs/solutions/`.
6
+
5
7
  ---
6
8
 
7
9
  ## Bug Track Template
@@ -2,6 +2,8 @@
2
2
 
3
3
  Choose the template matching the problem_type track (see `references/schema.yaml`).
4
4
 
5
+ **Citing code:** write a repo-relative path with the line or range (`<file>:<line>` or `<file>:<start>-<end>`), never a bare file name, and put the backticked symbol it points at in the same sentence. Link a tag or commit for code outside the repo or deleted code. Write placeholders such as `<file>:<line>` in examples. The content-integrity gate checks citations in `docs/solutions/`.
6
+
5
7
  ---
6
8
 
7
9
  ## Bug Track Template
@@ -426,7 +426,7 @@ Documentation is successful when ALL of the following are true:
426
426
  **Good documentation has:**
427
427
 
428
428
  - ✅ Exact error messages (copy-paste from output)
429
- - ✅ Specific file:line references
429
+ - ✅ Specific file:line references (see Citing code below)
430
430
  - ✅ Observable symptoms (what you saw, not interpretations)
431
431
  - ✅ Failed attempts documented (helps avoid wrong paths)
432
432
  - ✅ Technical explanation (not just "what" but "why")
@@ -434,6 +434,14 @@ Documentation is successful when ALL of the following are true:
434
434
  - ✅ Prevention guidance (how to catch early)
435
435
  - ✅ Cross-references (related issues)
436
436
 
437
+ **Citing code:**
438
+
439
+ - Write a repo-relative path with the line or range, as `<file>:<line>` or `<file>:<start>-<end>`. Never cite a bare file name.
440
+ - Put the backticked symbol the citation points at in the same sentence, so a moved line is caught.
441
+ - For code outside the repo, or code that has been deleted, link a tag or commit, not a path.
442
+ - In examples, write placeholders such as `<file>:<line>`, not real citations.
443
+ - The content-integrity gate checks the citations in `docs/solutions/` and fails on a missing file, a line outside the file, a span of only blanks or comments, or a named symbol that is not in the span.
444
+
437
445
  **Avoid:**
438
446
 
439
447
  - ❌ Vague descriptions ("something was wrong")
@@ -46,6 +46,8 @@ tags: [keyword1, keyword2, keyword3]
46
46
 
47
47
  [The actual fix that worked - provide specific details]
48
48
 
49
+ [Cite code as a repo-relative `<file>:<line>` or `<file>:<start>-<end>`, with the backticked symbol in the same sentence. Link a tag or commit for code outside the repo or deleted code. The content-integrity gate checks these citations.]
50
+
49
51
  **Code changes** (if applicable):
50
52
  ```ruby
51
53
  # Before (broken):
@@ -1,170 +0,0 @@
1
- import { createHash } from 'node:crypto';
2
- export type OperationObserverReasonCode = 'target-unavailable' | 'command-failed' | 'command-timeout' | 'command-output-limit' | 'file-limit' | 'file-output-limit' | 'file-read-failed' | 'remote-command-failed' | 'remote-command-output-limit' | 'remote-invalid-json' | 'remote-missing-field' | 'remote-item-limit' | 'remote-not-advanced' | 'commit-not-closed' | 'worktree-unstable';
3
- export interface RegisteredWorktreeParentIdentity {
4
- readonly targetRoot: string;
5
- readonly gitDir: string;
6
- readonly commonDir: string;
7
- readonly registeredWorktreeRoots: readonly string[];
8
- }
9
- export interface RegisteredWorktreeValidationOptions {
10
- readonly commandRunner?: OperationObserverCommandRunner;
11
- readonly limits?: OperationObserverLimits;
12
- readonly realPath?: (filePath: string) => string;
13
- }
14
- export type RegisteredWorktreeValidationResult = {
15
- readonly status: 'ok';
16
- readonly targetRoot: string;
17
- readonly gitDir: string;
18
- readonly commonDir: string;
19
- } | {
20
- readonly status: 'error';
21
- readonly reasonCode: OperationObserverReasonCode;
22
- };
23
- export type RemoteOperation = 'push' | 'pr-creation' | 'check-readback' | 'review-readback';
24
- export type RemoteReadbackPhase = 'before' | 'after';
25
- export interface OperationObserverSnapshot {
26
- readonly targetDigest: string;
27
- readonly repositoryRevisionDigest: string;
28
- readonly worktreeRevisionDigest: string;
29
- readonly commitClosure?: boolean;
30
- }
31
- export type OperationObserverResult = {
32
- readonly status: 'available';
33
- readonly snapshot: OperationObserverSnapshot;
34
- } | {
35
- readonly status: 'unavailable';
36
- readonly reasonCode: OperationObserverReasonCode;
37
- };
38
- export interface OperationObserverCommandResult {
39
- readonly status: number;
40
- readonly stdout: string;
41
- readonly stderr: string;
42
- readonly timedOut?: boolean;
43
- /** stdout was not valid UTF-8; `stdout` must not be trusted. */
44
- readonly invalidOutput?: boolean;
45
- }
46
- export interface OperationObserverRemoteCommandResult {
47
- readonly status: number;
48
- readonly stdout: string;
49
- readonly stderr: string;
50
- readonly timedOut?: boolean;
51
- }
52
- export type OperationObserverCommandRunner = (args: readonly string[], cwd: string, maxOutputBytes: number, timeoutMs: number) => OperationObserverCommandResult;
53
- export type OperationObserverRemoteCommandRunner = (executable: 'git' | 'gh', args: readonly string[], cwd: string, maxOutputBytes: number, timeoutMs: number) => OperationObserverRemoteCommandResult;
54
- export interface OperationObserverRemoteSnapshot {
55
- readonly resourceIdentity: string;
56
- readonly resourceRevisionIdentity: string;
57
- readonly pullRequest?: {
58
- readonly identity: string;
59
- readonly state: 'open' | 'closed' | 'merged';
60
- };
61
- readonly checkState?: 'completed-success' | 'completed-failure' | 'pending';
62
- readonly reviewDecision?: 'approved' | 'changes-requested' | 'commented' | 'pending';
63
- }
64
- export type OperationObserverRemoteResult = {
65
- readonly status: 'available';
66
- readonly snapshot: OperationObserverRemoteSnapshot;
67
- } | {
68
- readonly status: 'missing-resource';
69
- } | {
70
- readonly status: 'unavailable';
71
- readonly reasonCode: OperationObserverReasonCode;
72
- };
73
- export interface OperationObserverLimits {
74
- readonly maxCommandOutputBytes?: number;
75
- readonly maxCommandTimeoutMs?: number;
76
- readonly maxFiles?: number;
77
- readonly maxGitlinks?: number;
78
- readonly maxRemoteCommandOutputBytes?: number;
79
- readonly maxRemoteItems?: number;
80
- readonly maxTotalFileBytes?: number;
81
- readonly maxPathBytes?: number;
82
- }
83
- export interface OperationObserverFileStat {
84
- readonly isFile: boolean;
85
- readonly isSymbolicLink: boolean;
86
- readonly isDirectory: boolean;
87
- readonly mode: number;
88
- readonly size: number;
89
- readonly dev?: number | bigint;
90
- readonly ino?: number | bigint;
91
- readonly mtimeNs?: number | bigint;
92
- readonly ctimeNs?: number | bigint;
93
- }
94
- export interface OpencodeOperationObserverOptions {
95
- readonly targetDirectory: string;
96
- readonly commandRunner?: OperationObserverCommandRunner;
97
- readonly remoteCommandRunner?: OperationObserverRemoteCommandRunner;
98
- readonly fileReader?: (filePath: string) => Uint8Array;
99
- readonly symlinkReader?: (filePath: string) => Uint8Array;
100
- readonly statReader?: (filePath: string) => OperationObserverFileStat;
101
- readonly realPath?: (filePath: string) => string;
102
- readonly limits?: OperationObserverLimits;
103
- }
104
- export interface OpencodeOperationObserver {
105
- readonly targetDigest: string;
106
- validateRegisteredWorktree(candidateDirectory: string): RegisteredWorktreeValidationResult;
107
- snapshot(): Promise<OperationObserverResult>;
108
- remoteSnapshot?(operation: RemoteOperation, phase: RemoteReadbackPhase): Promise<OperationObserverRemoteResult>;
109
- }
110
- /** Git object format; selects the hash used for blob ids. */
111
- export type ObjectFormat = 'sha1' | 'sha256';
112
- export type WorktreeRecordKind = 'regular' | 'symlink' | 'gitlink' | 'missing';
113
- /**
114
- * One record per observed path. `id` is the git blob id of the raw bytes read
115
- * (a symlink's target bytes for a symlink), or the submodule `HEAD` for a
116
- * gitlink. A `missing` path (listed but gone by the time it was read) has an
117
- * empty `mode` and no `id`.
118
- */
119
- export interface WorktreeRecord {
120
- readonly path: string;
121
- readonly kind: WorktreeRecordKind;
122
- /** Git-style mode: `100644`, `100755`, `120000` or `160000`. */
123
- readonly mode: string;
124
- readonly id: string | undefined;
125
- }
126
- export declare function validateRegisteredWorktree(candidateDirectory: string, parentIdentity: RegisteredWorktreeParentIdentity, options?: RegisteredWorktreeValidationOptions): RegisteredWorktreeValidationResult;
127
- /**
128
- * Feeds one variable-length field into a digest as `<byte length>:<bytes>`, so
129
- * the boundary between two fields is part of what is hashed. Without it, a
130
- * file whose content spells out the next record would hash like two files.
131
- *
132
- * @internal Exported for the framing test only.
133
- */
134
- export declare function hashField(hash: ReturnType<typeof createHash>, field: string | Uint8Array): void;
135
- /**
136
- * What a gitlink path holds on disk: nothing checked out (`uninitialized`), a
137
- * checkout with no commit yet (`unborn`), or a checkout at a commit.
138
- *
139
- * @internal Exported for tests only.
140
- */
141
- export type GitlinkState = 'uninitialized' | 'unborn' | 'initialized';
142
- export interface HeadTreeEntry {
143
- readonly mode: string;
144
- readonly id: string;
145
- }
146
- /**
147
- * Gitlinks that only `HEAD` lists and that now have paths beneath them. A
148
- * gitlink in the index is current, so it is never displaced: a populated
149
- * directory without `.git` there is still malformed.
150
- *
151
- * `sortedPaths` must be in UTF-8 byte order, as the path set is.
152
- *
153
- * @internal Exported for tests only.
154
- */
155
- export declare function findDisplacedGitlinks(sortedPaths: readonly string[], indexModes: ReadonlyMap<string, string>, headTree: ReadonlyMap<string, HeadTreeEntry>): ReadonlySet<string>;
156
- /**
157
- * @internal Test hook: runs the worktree read on its own and returns the path
158
- * records beside the digest. The observer API does not expose records.
159
- */
160
- export declare function readWorktreeRecords(targetDirectory: string, options?: Omit<OpencodeOperationObserverOptions, 'targetDirectory' | 'remoteCommandRunner'>): {
161
- status: 'ok';
162
- digest: string;
163
- records: readonly WorktreeRecord[];
164
- headTree: ReadonlyMap<string, HeadTreeEntry>;
165
- commitClosure: boolean;
166
- } | {
167
- status: 'error';
168
- reasonCode: OperationObserverReasonCode;
169
- };
170
- export declare function createOpencodeOperationObserver(options: OpencodeOperationObserverOptions): OpencodeOperationObserver;