mustflow 2.74.7 → 2.75.1

package/dist/core/public-json-contracts.js

@@ -232,6 +232,42 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
             '--json',
         ],
     },
+    {
+        id: 'code-outline-report',
+        schemaFile: 'code-outline-report.schema.json',
+        producer: 'mf script-pack run code/outline scan <path...> --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'code/outline',
+            'scan',
+            'node_modules/mustflow/dist/cli/index.js',
+            '--json',
+        ],
+    },
+    {
+        id: 'code-symbol-read-report',
+        schemaFile: 'code-symbol-read-report.schema.json',
+        producer: 'mf script-pack run code/symbol-read read <path> --start-line <line> --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'script-pack',
+            'run',
+            'code/symbol-read',
+            'read',
+            'node_modules/mustflow/dist/cli/index.js',
+            '--start-line',
+            '1',
+            '--end-line',
+            '10',
+            '--json',
+        ],
+    },
     {
         id: 'text-budget-report',
         schemaFile: 'text-budget-report.schema.json',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.74.7",
+  "version": "2.75.1",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -64,6 +64,14 @@ Current schemas:
   and associated report schemas
 - `script-pack-suggestion-report.schema.json`: output of `mf script-pack suggest --json`, containing
   path, skill, phase, and changed-file evidence used to recommend optional script-pack helpers
+- `code-outline-report.schema.json`: output of
+  `mf script-pack run code/outline scan <path...> --json`, containing a bounded TypeScript and
+  JavaScript source outline with file hashes, symbol names, declaration kinds, line ranges,
+  signatures, export flags, static return metadata, and stable input-limit finding codes
+- `code-symbol-read-report.schema.json`: output of
+  `mf script-pack run code/symbol-read read <path> --start-line <line> --json`, containing a
+  focused source snippet selected by outline symbol line or explicit line range with file hash,
+  resolved line metadata, optional symbol and static return metadata, and stable range/read finding codes
 - `text-budget-report.schema.json`: output of
   `mf script-pack run core/text-budget check <path...> --json`, containing
   exact text-budget metrics, input content hashes, policy metadata, findings, and JSON Pointer field

package/schemas/code-outline-report.schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/code-outline-report.schema.json",
+  "title": "mustflow code-outline report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "policy",
+    "input_hash",
+    "files",
+    "symbols",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "code" },
+    "script_id": { "const": "outline" },
+    "script_ref": { "const": "code/outline" },
+    "action": { "const": "scan" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "files": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/file" }
+    },
+    "symbols": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/symbol" }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "language": {
+      "enum": ["typescript", "tsx", "javascript", "jsx", "javascript-module", "javascript-commonjs"]
+    },
+    "symbolKind": {
+      "enum": ["function", "class", "interface", "type", "enum", "variable"]
+    },
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["max_file_bytes", "max_files", "extensions", "ignored_directories"],
+      "properties": {
+        "max_file_bytes": { "type": "integer", "minimum": 1 },
+        "max_files": { "type": "integer", "minimum": 1 },
+        "extensions": { "$ref": "#/$defs/stringArray" },
+        "ignored_directories": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "file": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path", "language", "sha256", "size_bytes", "line_count", "symbol_count"],
+      "properties": {
+        "kind": { "const": "source_file" },
+        "path": { "type": "string" },
+        "language": { "$ref": "#/$defs/language" },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "size_bytes": { "type": "integer", "minimum": 0 },
+        "line_count": { "type": "integer", "minimum": 0 },
+        "symbol_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "symbol": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "path",
+        "language",
+        "kind",
+        "name",
+        "start_line",
+        "end_line",
+        "signature",
+        "exported",
+        "async",
+        "return_type",
+        "return_behavior",
+        "return_count",
+        "return_lines",
+        "return_preview",
+        "parent",
+        "content_sha256"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "language": { "$ref": "#/$defs/language" },
+        "kind": { "$ref": "#/$defs/symbolKind" },
+        "name": { "type": "string" },
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": "integer", "minimum": 1 },
+        "signature": { "type": "string" },
+        "exported": { "type": "boolean" },
+        "async": { "type": "boolean" },
+        "return_type": { "type": ["string", "null"] },
+        "return_behavior": {
+          "enum": ["value", "void", "implicit_undefined", "mixed", "throws_only", "unknown"]
+        },
+        "return_count": { "type": "integer", "minimum": 0 },
+        "return_lines": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "return_preview": { "type": ["string", "null"] },
+        "parent": { "type": ["string", "null"] },
+        "content_sha256": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path"],
+      "properties": {
+        "code": {
+          "enum": [
+            "code_outline_path_outside_root",
+            "code_outline_unreadable_path",
+            "code_outline_unsupported_file",
+            "code_outline_file_too_large",
+            "code_outline_max_files_exceeded"
+          ]
+        },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/code-symbol-read-report.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/code-symbol-read-report.schema.json",
+  "title": "mustflow code-symbol-read report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "policy",
+    "input_hash",
+    "target",
+    "snippet",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "code" },
+    "script_id": { "const": "symbol-read" },
+    "script_ref": { "const": "code/symbol-read" },
+    "action": { "const": "read" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "target": {
+      "anyOf": [
+        { "$ref": "#/$defs/target" },
+        { "type": "null" }
+      ]
+    },
+    "snippet": {
+      "anyOf": [
+        { "$ref": "#/$defs/snippet" },
+        { "type": "null" }
+      ]
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "language": {
+      "enum": ["typescript", "tsx", "javascript", "jsx", "javascript-module", "javascript-commonjs"]
+    },
+    "symbolKind": {
+      "enum": ["function", "class", "interface", "type", "enum", "variable"]
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["start_line", "end_line", "context_lines", "max_file_bytes", "max_snippet_lines"],
+      "properties": {
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": ["integer", "null"], "minimum": 1 },
+        "context_lines": { "type": "integer", "minimum": 0 },
+        "max_file_bytes": { "type": "integer", "minimum": 1 },
+        "max_snippet_lines": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "symbol": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "path",
+        "language",
+        "kind",
+        "name",
+        "start_line",
+        "end_line",
+        "signature",
+        "exported",
+        "async",
+        "return_type",
+        "return_behavior",
+        "return_count",
+        "return_lines",
+        "return_preview",
+        "parent",
+        "content_sha256"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "language": { "$ref": "#/$defs/language" },
+        "kind": { "$ref": "#/$defs/symbolKind" },
+        "name": { "type": "string" },
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": "integer", "minimum": 1 },
+        "signature": { "type": "string" },
+        "exported": { "type": "boolean" },
+        "async": { "type": "boolean" },
+        "return_type": { "type": ["string", "null"] },
+        "return_behavior": {
+          "enum": ["value", "void", "implicit_undefined", "mixed", "throws_only", "unknown"]
+        },
+        "return_count": { "type": "integer", "minimum": 0 },
+        "return_lines": {
+          "type": "array",
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "return_preview": { "type": ["string", "null"] },
+        "parent": { "type": ["string", "null"] },
+        "content_sha256": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "language",
+        "sha256",
+        "size_bytes",
+        "line_count",
+        "requested_start_line",
+        "requested_end_line",
+        "resolved_start_line",
+        "resolved_end_line",
+        "context_start_line",
+        "context_end_line",
+        "symbol"
+      ],
+      "properties": {
+        "path": { "type": "string" },
+        "language": { "$ref": "#/$defs/language" },
+        "sha256": { "$ref": "#/$defs/sha256" },
+        "size_bytes": { "type": "integer", "minimum": 0 },
+        "line_count": { "type": "integer", "minimum": 0 },
+        "requested_start_line": { "type": "integer", "minimum": 1 },
+        "requested_end_line": { "type": ["integer", "null"], "minimum": 1 },
+        "resolved_start_line": { "type": ["integer", "null"], "minimum": 1 },
+        "resolved_end_line": { "type": ["integer", "null"], "minimum": 1 },
+        "context_start_line": { "type": ["integer", "null"], "minimum": 1 },
+        "context_end_line": { "type": ["integer", "null"], "minimum": 1 },
+        "symbol": {
+          "anyOf": [
+            { "$ref": "#/$defs/symbol" },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+    "snippet": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "start_line", "end_line", "text"],
+      "properties": {
+        "path": { "type": "string" },
+        "start_line": { "type": "integer", "minimum": 1 },
+        "end_line": { "type": "integer", "minimum": 1 },
+        "text": { "type": "string" }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path", "start_line", "end_line"],
+      "properties": {
+        "code": {
+          "enum": [
+            "code_symbol_read_path_outside_root",
+            "code_symbol_read_unreadable_path",
+            "code_symbol_read_invalid_range",
+            "code_symbol_read_no_symbol_at_line",
+            "code_symbol_read_snippet_too_large"
+          ]
+        },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string" },
+        "start_line": { "type": ["integer", "null"], "minimum": 1 },
+        "end_line": { "type": ["integer", "null"], "minimum": 1 }
+      }
+    }
+  }
+}

package/templates/default/i18n.toml

@@ -505,7 +505,7 @@ translations = {}
 [documents."skill.codebase-orientation"]
 source = "locales/en/.mustflow/skills/codebase-orientation/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 4
 translations = {}
 
 [documents."skill.heuristic-candidate-selection"]

package/templates/default/locales/en/.mustflow/skills/codebase-orientation/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.codebase-orientation
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: codebase-orientation
@@ -71,9 +71,15 @@ Build a concise, evidence-based map of an unfamiliar repository area before plan
 2. Read the nearest repository instructions and matching skill routes before inspecting source files.
 3. Use navigation aids in order:
    - current changed files or user-named paths;
+   - read-only script-pack helpers such as `code/outline` and `code/symbol-read` when the
+     installed CLI exposes them and repository or host policy allows running the read-only helper;
    - `REPO_MAP.md` only when broader repository navigation is needed;
    - file search for names, exported symbols, command ids, schema ids, route ids, and test names.
    Treat generated maps and docs as pointers, not proof.
+   Prefer `code/outline` before reading large TypeScript or JavaScript files in repeated line
+   windows, then use `code/symbol-read` to read the selected symbol range or a bounded explicit
+   line range. If script-pack execution is not authorized, fall back to ordinary file search and
+   targeted reads instead of inventing script output.
 4. Watch for stalled observation.
    - If the same file, path, list, search, or generated-map lookup repeats without new evidence,
      stop that branch and switch to `evidence-stall-breaker`.

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.74.7"
+version = "2.75.1"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"