guardlink 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to GuardLink CLI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.1] — 2026-03-12
+
+### Fixed
+
+- **GAL reference (`/gal`, `guardlink gal`)**: Fixed all syntax examples to match the actual parser — descriptions now correctly show `-- "quoted text"` format instead of the non-functional `: text` format; severity now shows bracket notation `[high]` / `[P0]` instead of `severity:high`; `@flows` now shows `->` arrow syntax instead of `to`; `@validates` now shows `for` preposition instead of `on`; `@owns` now includes the required `for` preposition; `@mitigates` now documents `using` as the primary keyword (with `with` as v1 compat)
+- **GAL reference**: Added missing documentation for external references (`cwe:CWE-89`, `owasp:A03:2021`, `capec:CAPEC-66`, `attack:T1190`) on `@threat` and `@exposes` annotations
+- **GAL reference**: Added missing `@boundary` alternate syntaxes (`@boundary between A and B`, `@boundary A | B`) and `(#id)` support
+- **GAL reference**: Added missing standalone `@shield` single-line marker (was only documenting `@shield:begin/end` blocks)
+- **TUI `/help`**: Added missing `/unannotated` command to the help output (was registered and functional but not listed)
+- **CLI version**: Fixed `guardlink --version` reporting `1.1.0` instead of the actual package version
+
+### Changed
+
+- **GAL reference**: Added new "External References" section explaining `cwe:`, `owasp:`, `capec:`, `attack:` ref syntax
+- **GAL reference**: Updated Tips section with description format, severity format, and `@flows ->` syntax reminders
+- **Annotations**: Changed `@comment` to `@audit` on agent-launcher timeout note for better governance visibility
+- **Annotations**: Added `@audit` to MCP suggest module, added workspace-related controls to definitions
+
+## [1.4.0] — 2026-02-27
+
+### Added
+
+- **Workspace**: Multi-repo workspace support — link N service repos into a unified threat model with cross-repo tag resolution, weekly diff tracking, and merged dashboards
+- **Workspace**: `guardlink link-project <repos...> --workspace <name> --registry <url>` — scaffold workspace.yaml in each repo, auto-detect repo names from git/package.json/Cargo.toml, inject cross-repo context into agent instruction files
+- **Workspace**: `guardlink link-project --add <repo> --from <existing>` — add a repo to an existing workspace with sibling auto-discovery
+- **Workspace**: `guardlink link-project --remove <name> --from <existing>` — remove a repo from workspace, update all siblings found on disk
+- **Workspace**: `guardlink merge <files...>` — merge N per-repo report JSONs into a unified MergedReport with tag registry, cross-repo reference resolution, stale/schema warnings, and aggregated stats
+- **Workspace**: `--diff-against <prev.json>` flag on merge for week-over-week risk tracking (assets/threats/mitigations/exposures added/removed, risk trend, unresolved ref changes)
+- **Workspace**: `-o <file>` dashboard HTML output + `--json <file>` merged JSON output + `--summary-only` text mode
+- **CLI**: `guardlink report --format json` — JSON report output with metadata (repo, workspace, commit SHA, schema version)
+- **TUI**: `/workspace` — show workspace config, sibling repos, registries
+- **TUI**: `/link` — link repos with `--add`/`--remove` support
+- **TUI**: `/merge` — merge reports with `--json`, `--diff-against`, `-o` flags
+- **MCP**: `guardlink_workspace_info` tool — returns workspace name, this_repo identity, sibling tag prefixes, and cross-repo annotation rules for agents
+- **Parser**: External reference detection — scans relationship annotations for tags with dot-prefix matching sibling repo names from workspace.yaml, populates `ThreatModel.external_refs`
+- **Types**: `ExternalRef` interface, `ThreatModel.external_refs` field, `ReportMetadata` with repo/workspace/commit_sha/schema_version
+- **CI**: `examples/ci/per-repo-report.yml` — per-repo workflow: validate on PRs (diff + SARIF + PR comment), generate + upload report JSON on push to main
+- **CI**: `examples/ci/workspace-merge.yml` — weekly workspace merge workflow: download all repo artifacts, merge, dashboard, weekly diff, optional GitHub Pages + Slack
+- **Docs**: `docs/WORKSPACE.md` — multi-repo setup guide, workspace.yaml spec, cross-repo annotation rules, merge behavior, CI integration, weekly workflow
+
+### Changed
+
+- **MCP**: Server version bumped to 1.4.0
+
 ## [1.3.0] — 2026-02-27
 
 ### Added

package/README.md

@@ -59,6 +59,9 @@ To uninstall: `npm unlink -g guardlink`
 # Initialize in your project (detects your AI agent automatically)
 guardlink init
 
+# Let AI annotate your project - Launch a coding agent to add annotations
+guardlink annotate [prompt]
+
 # Let your AI coding agent annotate, or write annotations manually
 # Then validate
 guardlink validate .
@@ -151,6 +154,7 @@ GuardLink ships an MCP server and behavioral directives for AI coding agents. Af
 | `guardlink_dashboard` | Generate HTML dashboard |
 | `guardlink_sarif` | Export SARIF 2.1.0 |
 | `guardlink_diff` | Compare threat model against a git ref |
+| `guardlink_workspace_info` | Workspace config, sibling repos, tag prefixes for cross-repo annotations |
 
 **Resources:** `guardlink://model`, `guardlink://definitions`, `guardlink://config`
 
@@ -161,6 +165,7 @@ GuardLink ships an MCP server and behavioral directives for AI coding agents. Af
 | Command | Description |
 |---------|-------------|
 | `guardlink init [dir]` | Initialize project with definitions, config, and agent integration |
+| `guardlink annotate [prompt]` | Launch a coding agent to add annotations |
 | `guardlink parse [dir]` | Parse all annotations, output ThreatModel JSON |
 | `guardlink status [dir]` | Coverage summary: assets, threats, mitigations, exposures |
 | `guardlink validate [dir]` | Check for syntax errors, dangling refs, duplicate IDs |
@@ -173,12 +178,16 @@ GuardLink ships an MCP server and behavioral directives for AI coding agents. Af
 | `guardlink sarif [dir]` | Export unmitigated exposures as SARIF 2.1.0 |
 | `guardlink threat-report [fw]` | AI threat report (stride/dread/pasta/attacker/rapid/general) |
 | `guardlink threat-reports` | List saved AI threat reports |
-| `guardlink annotate [prompt]` | Launch a coding agent to add annotations |
 | `guardlink review [dir]` | Interactive governance review — accept, remediate, or skip unmitigated exposures |
 | `guardlink review --list` | List reviewable exposures without prompting |
 | `guardlink clear [dir]` | Remove all annotations from source files (with `--dry-run` preview) |
 | `guardlink sync [dir]` | Sync agent instruction files with current threat model |
 | `guardlink unannotated [dir]` | List source files with no annotations |
+| `guardlink link-project <repos...>` | Link repos into a shared workspace for cross-repo threat modeling |
+| `guardlink link-project --add <repo>` | Add a repo to an existing workspace |
+| `guardlink link-project --remove <name>` | Remove a repo from a workspace |
+| `guardlink merge <files...>` | Merge per-repo report JSONs into a unified workspace dashboard |
+| `guardlink report --format json` | Generate report JSON with metadata (repo, workspace, commit SHA) |
 | `guardlink config` | Set AI provider and API key |
 | `guardlink mcp` | Start MCP server for AI agent integration |
 
@@ -282,6 +291,10 @@ jobs:
 
 See [`examples/github-action.yml`](examples/github-action.yml) for a full example with PR comments and SARIF upload.
 
+### Multi-Repo CI
+
+For workspace setups, GuardLink provides two additional workflow templates: a per-repo workflow that generates report JSON artifacts on every push, and a workspace merge workflow that runs weekly to combine all repos into a unified dashboard. See the [CI setup guide](examples/ci/README.md) for step-by-step instructions.
+
 ### What CI Catches
 
 - **New route, no annotations:** `guardlink diff` shows "+1 endpoint, 0 mitigations" — the team sees the gap.
@@ -294,6 +307,35 @@ See [`examples/github-action.yml`](examples/github-action.yml) for a full exampl
 
 ---
 
+## Multi-Repo Workspaces
+
+In microservices architectures, a single repo only has part of the security picture. `PaymentService` is defined in `repo-payments`, exposed in `repo-gateway`, mitigated in `repo-auth-lib`. GuardLink workspaces link these repos so the threat model spans service boundaries.
+
+```bash
+# Link three repos into a workspace
+guardlink link-project ./payment-svc ./auth-lib ./api-gateway \
+  --workspace acme-platform
+
+# Each repo gets .guardlink/workspace.yaml + agent files updated with cross-repo context
+# Agents now know about sibling services and use tag prefixes like #payment-svc.refund
+
+# Generate per-repo JSON reports (in each repo or in CI)
+guardlink report --format json -o guardlink-report.json
+
+# Merge all reports into a unified dashboard
+guardlink merge payment-svc.json auth-lib.json api-gateway.json \
+  -o dashboard.html --json merged.json
+
+# Week-over-week diff for security leads
+guardlink merge *.json --diff-against last-week.json --json merged.json
+```
+
+Annotations reference sibling repos by tag prefix — `@flows #request from #api-gateway.router to #payment-svc.refund` — and these references resolve during merge. `guardlink validate` flags them as external refs locally, but they're expected and won't block CI.
+
+For automated weekly dashboards, see the [CI setup guide](examples/ci/README.md). Full workspace documentation: [docs/WORKSPACE.md](docs/WORKSPACE.md).
+
+---
+
 ## Real-World Results
 
 We tested GuardLink + Claude Code on [vuln-node.js-express.js-app](https://github.com/SirAppSec/vuln-node.js-express.js-app), a deliberately vulnerable Express.js application with 37 documented vulnerability types.

package/dist/agents/launcher.d.ts

@@ -13,7 +13,7 @@
  * @exposes #agent-launcher to #prompt-injection [medium] cwe:CWE-77 -- "User prompt passed to agent CLI as argument"
  * @audit #agent-launcher -- "Prompt content is opaque to agent binary; injection risk depends on agent implementation"
  * @exposes #agent-launcher to #dos [low] cwe:CWE-400 -- "No timeout on foreground spawn; agent controls duration"
- * @comment -- "Timeout intentionally omitted for interactive sessions; inline mode has implicit control"
+ * @audit #agent-launcher -- "Timeout intentionally omitted for interactive sessions; inline mode has implicit control"
  * @flows UserPrompt -> #agent-launcher via launchAgent -- "Prompt input path"
  * @flows #agent-launcher -> AgentProcess via spawn -- "Process spawn path"
  * @flows AgentProcess -> #agent-launcher via stdout -- "Agent output capture"

package/dist/agents/launcher.js

@@ -13,7 +13,7 @@
  * @exposes #agent-launcher to #prompt-injection [medium] cwe:CWE-77 -- "User prompt passed to agent CLI as argument"
  * @audit #agent-launcher -- "Prompt content is opaque to agent binary; injection risk depends on agent implementation"
  * @exposes #agent-launcher to #dos [low] cwe:CWE-400 -- "No timeout on foreground spawn; agent controls duration"
- * @comment -- "Timeout intentionally omitted for interactive sessions; inline mode has implicit control"
+ * @audit #agent-launcher -- "Timeout intentionally omitted for interactive sessions; inline mode has implicit control"
  * @flows UserPrompt -> #agent-launcher via launchAgent -- "Prompt input path"
  * @flows #agent-launcher -> AgentProcess via spawn -- "Process spawn path"
  * @flows AgentProcess -> #agent-launcher via stdout -- "Agent output capture"

package/dist/cli/index.d.ts

@@ -18,6 +18,8 @@
  *   guardlink mcp                     Start MCP server (stdio) for Claude Code, Cursor, etc.
  *   guardlink tui [dir]               Interactive TUI with slash commands + AI chat
  *   guardlink gal                     Display GAL annotation language quick reference
+ *   guardlink link-project <repos...>  Link repos into a shared workspace
+ *   guardlink merge <files...>         Merge repo reports into unified dashboard
  *
  * @exposes #cli to #path-traversal [high] cwe:CWE-22 -- "User-supplied dir argument resolved via path.resolve"
  * @mitigates #cli against #path-traversal using #path-validation -- "resolve() canonicalizes paths; cwd-relative by design"

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}