feat: ecosystem architecture enhancements (Graph, Loop, Context, Harness)

.github/workflows/release.yml

@@ -69,3 +69,27 @@ jobs:
           # Optional secrets used by some repos' goreleaser configs:
           HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
           TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+
+      # Sign release artifacts with cosign keyless signing. The
+      # id-token: write permission above enables OIDC federation with
+      # Fulcio's root CA — no long-lived signing keys to manage.
+      - name: Install cosign
+        uses: sigstore/cosign-installer@d8a3f51ef971a853e51de6231a89f4483c5a7a0e # v3.4.0
+
+      - name: Sign release checksums with cosign
+        run: |
+          set -euo pipefail
+          # Download the checksums artifact produced by goreleaser.
+          gh release download "${GITHUB_REF_NAME}" --pattern "checksums.txt" -D dist/
+          # Sign with keyless OIDC — output is dist/checksums.txt.sig (bundle).
+          cosign sign-blob \
+            --yes \
+            --output-signature dist/checksums.txt.sig \
+            --output-certificate dist/checksums.txt.cert \
+            dist/checksums.txt
+          # Upload the signature and certificate back to the release.
+          gh release upload "${GITHUB_REF_NAME}" \
+            dist/checksums.txt.sig \
+            dist/checksums.txt.cert
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.goreleaser.yml

@@ -128,6 +128,12 @@ sboms:
     documents:
       - "${artifact}.spdx.sbom.json"
 
+# ---------------------------------------------------------------------------
+# Signing — cosign keyless signing of checksums is performed in the
+# release workflow (post-goreleaser) so the OIDC token from GitHub Actions
+# is available. The checksums.txt artifact is signed there.
+# ---------------------------------------------------------------------------
+
 release:
   draft: false
   prerelease: auto

README.md

@@ -80,6 +80,35 @@ Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) for a smooth
 | **Code** | `LSP` diagnostics, `CodeSearch`, `NotebookEdit`, `SQL` (read-only DB exploration) |
 | **MCP** | `ListMcpResources`, `ReadMcpResource` |
 
+### Portable Execution Graph
+
+Export the latest or a selected Hawk session as validated graph nodes, edges,
+and lifecycle events:
+
+```bash
+hawk graph export
+hawk graph export <session-id>
+hawk graph export <session-id> --trace-checkpoint abc123def456
+hawk graph export --mission-dir /path/to/mission
+
+# Explicitly privacy-normalize and sync the graph for a connected cloud project
+hawk cloud graph sync <session-id>
+hawk cloud graph sync --mission-dir /path/to/mission
+```
+
+The export contains metadata and hashes, not prompts, tool arguments/results,
+policy reasons, verification evidence, or runtime output. Trace remains
+available separately as `hawk trace graph export`. Persisted chat sessions
+automatically append privacy-safe permission, enabled approval-gate, and
+`VerifyPlanExecution` summaries for subsequent graph exports. Yaad memory
+subgraphs and Hawk code-index chunks actually selected for inference are also
+journaled as metadata-only knowledge nodes and linked to the session. Inspect's
+observed bridge path similarly journals bounded, metadata-only report/finding
+quality subgraphs. Sight exposes the same observed bridge boundary for
+metadata-only code-review quality subgraphs. Mission runs also persist a
+portable `mission-graph.json`; the mission form is validated and synchronized
+explicitly with the `--mission-dir` variants above.
+
 ### Multi-Agent Mission Mode (optional)
 
 For larger tasks, decompose work into parallel feature branches (power-user / future team workflows):
@@ -271,6 +300,7 @@ Endpoints: `GET /v1/health`, `GET /v1/ready` (dependency-aware readiness), `POST
 hawk mission "Add auth, rate limiting, and logging"
 hawk mission --workers 6 "Refactor into microservices"
 hawk mission --dry-run "What would this decompose into?"
+hawk mission --from-tasks                 # Execute validated dependency waves
 ```
 
 ## Providers
@@ -375,12 +405,15 @@ You may keep a **personal** parent **`go.work`** that lists alternate clones on
 | **eyrie** | [GrayCodeAI/eyrie](https://github.com/GrayCodeAI/eyrie) | LLM provider runtime |
 | **sight** | [GrayCodeAI/sight](https://github.com/GrayCodeAI/sight) | Diff-based code review (`hawk sight`) |
 | **inspect** | [GrayCodeAI/inspect](https://github.com/GrayCodeAI/inspect) | Site audit library |
-| **tok** | [GrayCodeAI/tok](https://github.com/GrayCodeAI/tok) | Tokenizer & compression |
+| **tok** | [GrayCodeAI/tok](https://github.com/GrayCodeAI/tok) | Compression, redaction, token/cost budgets, and privacy-safe runtime graph facts |
 | **yaad** | [GrayCodeAI/yaad](https://github.com/GrayCodeAI/yaad) | Graph-based memory |
 | **trace** | [GrayCodeAI/trace](https://github.com/GrayCodeAI/trace) | Session capture and replay engine mounted as `hawk trace ...` |
 | **hawk-core-contracts** | [GrayCodeAI/hawk-core-contracts](https://github.com/GrayCodeAI/hawk-core-contracts) | Shared contracts and neutral cross-repo vocabulary |
 
 For the consolidated repo map and the current-vs-proposed architecture diagrams, see [docs/architecture/hawk-current-vs-proposed.md](docs/architecture/hawk-current-vs-proposed.md).
+For execution-graph ownership, automatic capture seams, export/sync commands,
+and the Trace correlation contract, see
+[docs/architecture/execution-graph.md](docs/architecture/execution-graph.md).
 
 ## Development
 

api/openapi.yaml

@@ -125,6 +125,154 @@ components:
         tool_calls:
           type: integer
 
+    GraphScope:
+      type: object
+      properties:
+        tenant_id:
+          type: string
+        project_id:
+          type: string
+        repository_id:
+          type: string
+
+    GraphRef:
+      type: object
+      required: [kind, id]
+      properties:
+        kind:
+          type: string
+          enum: [system, knowledge, execution, policy, quality, operations]
+        id:
+          type: string
+
+    GraphArtifactRef:
+      type: object
+      required: [uri]
+      properties:
+        uri:
+          type: string
+        digest:
+          type: string
+        media_type:
+          type: string
+
+    GraphProvenance:
+      type: object
+      required: [producer]
+      properties:
+        producer:
+          type: string
+        version:
+          type: string
+        source_id:
+          type: string
+        evidence:
+          type: array
+          items:
+            $ref: "#/components/schemas/GraphArtifactRef"
+
+    GraphNode:
+      type: object
+      required: [id, kind, created_at, provenance]
+      properties:
+        id:
+          type: string
+        kind:
+          type: string
+          enum: [system, knowledge, execution, policy, quality, operations]
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        created_at:
+          type: string
+          format: date-time
+        effective_at:
+          type: string
+          format: date-time
+        provenance:
+          $ref: "#/components/schemas/GraphProvenance"
+        attributes:
+          type: object
+          additionalProperties:
+            type: string
+
+    GraphEdge:
+      type: object
+      required: [id, kind, from, to, created_at, provenance]
+      properties:
+        id:
+          type: string
+        kind:
+          type: string
+          enum: [contains, depends_on, references, produced, governed_by, validated_by]
+        from:
+          $ref: "#/components/schemas/GraphRef"
+        to:
+          $ref: "#/components/schemas/GraphRef"
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        created_at:
+          type: string
+          format: date-time
+        effective_at:
+          type: string
+          format: date-time
+        provenance:
+          $ref: "#/components/schemas/GraphProvenance"
+        attributes:
+          type: object
+          additionalProperties:
+            type: string
+
+    GraphEvent:
+      type: object
+      required: [id, type, subject, occurred_at, provenance]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [created, updated, transitioned, observed, deleted]
+        subject:
+          $ref: "#/components/schemas/GraphRef"
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        occurred_at:
+          type: string
+          format: date-time
+        correlation_id:
+          type: string
+        causation_id:
+          type: string
+        idempotency_key:
+          type: string
+        provenance:
+          $ref: "#/components/schemas/GraphProvenance"
+
+    ExecutionGraph:
+      type: object
+      required: [schema_version, generated_at, scope, nodes, edges, events]
+      properties:
+        schema_version:
+          type: string
+          enum: [hawk.graph/v1]
+        generated_at:
+          type: string
+          format: date-time
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        nodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/GraphNode"
+        edges:
+          type: array
+          items:
+            $ref: "#/components/schemas/GraphEdge"
+        events:
+          type: array
+          items:
+            $ref: "#/components/schemas/GraphEvent"
+
     Message:
       type: object
       properties:
@@ -259,6 +407,8 @@ tags:
     description: Session management
   - name: messages
     description: Message history
+  - name: graphs
+    description: Portable read-only execution graph projections
   - name: stats
     description: Usage statistics
   - name: review
@@ -458,6 +608,72 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
 
+  /v1/sessions/{id}/graph:
+    get:
+      tags: [graphs]
+      summary: Project a persisted session as a portable execution graph
+      description: |
+        Returns Hawk's privacy-safe, read-only `hawk.graph/v1` projection.
+        Prompt text, tool arguments, tool output, and verification details are
+        excluded. Explicit Trace checkpoint IDs are additive to authoritative
+        Trace session correlation performed by Hawk.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            maxLength: 128
+            pattern: '^[A-Za-z0-9._-]+$'
+        - name: repository
+          in: query
+          description: Optional repository scope override.
+          schema:
+            type: string
+            maxLength: 256
+        - name: trace_checkpoint
+          in: query
+          description: Optional 12-character lowercase hexadecimal Trace checkpoint ID. May be repeated up to 64 times.
+          schema:
+            type: array
+            maxItems: 64
+            items:
+              type: string
+              pattern: '^[0-9a-f]{12}$'
+          style: form
+          explode: true
+      responses:
+        "200":
+          description: Portable execution graph
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExecutionGraph"
+        "400":
+          description: Invalid session, repository, or checkpoint input
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: Session not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "503":
+          description: Graph projection is not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
   /v1/stats:
     get:
       tags: [stats]

cmd/agent.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -18,6 +19,8 @@ var agentCmd = &cobra.Command{
 	Long:  "Create, list, and manage custom agent personas stored in Hawk user state.",
 }
 
+var agentListJSON bool
+
 var agentListCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List all available agents",
@@ -54,17 +57,29 @@ func init() {
 	agentCreateCmd.Flags().StringVarP(&agentCreateDesc, "description", "d", "", "Agent description")
 	agentCreateCmd.Flags().StringVarP(&agentCreateModel, "model", "m", "", "Model to use (empty = inherit)")
 
+	agentListCmd.Flags().BoolVar(&agentListJSON, "json", false, "output agents as JSON")
 	agentCmd.AddCommand(agentListCmd)
 	agentCmd.AddCommand(agentCreateCmd)
 	agentCmd.AddCommand(agentShowCmd)
 	agentCmd.AddCommand(agentRemoveCmd)
 }
 
-func runAgentList(_ *cobra.Command, _ []string) error {
+func runAgentList(cmd *cobra.Command, _ []string) error {
 	all, err := agents.ListAll()
 	if err != nil {
 		return err
 	}
+	if agentListJSON {
+		if all == nil {
+			all = []*agents.Agent{}
+		}
+		out, err := json.MarshalIndent(all, "", "  ")
+		if err != nil {
+			return fmt.Errorf("marshaling agents: %w", err)
+		}
+		cmd.Println(string(out))
+		return nil
+	}
 	if len(all) == 0 {
 		fmt.Printf("No agents found. Create one with: hawk agent create <name>\n")
 		fmt.Printf("Agent directory: %s\n", agents.DefaultDir())
@@ -80,7 +95,10 @@ func runAgentList(_ *cobra.Command, _ []string) error {
 		}
 		desc := a.Description
 		if len(desc) > 50 {
-			desc = desc[:50] + "..."
+			// Rune-safe truncation: never split a multibyte UTF-8 sequence.
+			if runes := []rune(desc); len(runes) > 50 {
+				desc = string(runes[:50]) + "..."
+			}
 		}
 		_, _ = fmt.Fprintf(w, "%s\t%s\t%s\n", a.Name, model, desc)
 	}