feat: more updates to the canary implementation

benjivesterby · benjivesterby · commit 04392771f446 · 2025-09-20T17:41:24.000-04:00
diff --git a/.github/compass.yml b/.github/compass.yml
@@ -0,0 +1,26 @@
+name: canary
+id: 'ari:cloud:compass:89436501-45fd-498f-9c7c-b0db10b968cb:component/d819e7ce-7ec1-48ae-b718-cb3459fc6e06/41e70807-ff9f-4225-8e75-83c73d405ad6'
+slug: canary
+description: 'Creator, Manager and Manager of Agent Prompts and Canary Tokens in Agent Repositories'
+configVersion: 1
+typeId: APPLICATION
+ownerId: 'ari:cloud:identity::team/94046dbf-b5f2-435e-bd32-3aee54446e1f'
+fields:
+  lifecycle: Pre-release
+  tier: 4
+  isMonorepoProject: false
+links:
+  - name: null
+    type: REPOSITORY
+    url: 'https://github.com/codeprosorg/canary'
+  - name: ''
+    type: PROJECT
+    url: 'https://devnw.atlassian.net/browse/CP'
+relationships: {}
+labels:
+  - 'source:github'
+  - synced-with-jsm
+customFields: null
+
+# Learn more about formatting compass.yml:
+# https://go.atlassian.com/compass-yml-format
diff --git a/.github/pcapcompare-profiles/tcpdump-default.json b/.github/pcapcompare-profiles/tcpdump-default.json
diff --git a/.github/pcapcompare-profiles/tshark-default.json b/.github/pcapcompare-profiles/tshark-default.json
diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml
@@ -1,5 +1,27 @@
 name: canary
 on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with: { go-version: '1.25' }
+      - name: Build scanner
+        run: go build -o ./bin/canary ./tools/canary
+      - name: Generate status
+        run: ./bin/canary --root . --out status.json --csv status.csv
+      - name: Self-verify
+        run: ./bin/canary --root tools/canary --verify GAP_ANALYSIS.md --strict
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: canary-status
+          path: |
+            status.json
+            status.csv
+name: canary
+on: [push, pull_request]
 jobs:
   scan:
     runs-on: ubuntu-latest
diff --git a/GAP_ANALYSIS.md b/GAP_ANALYSIS.md
@@ -0,0 +1,4 @@
+# Requirements Gap Analysis (Self)
+
+✅ CBIN-101
+✅ CBIN-102
diff --git a/Makefile b/Makefile
@@ -152,6 +152,16 @@ release:
 	git tag -a ${tag} -m "${tag}"
 	git push origin ${tag}
 
+# Canary targets
+canary:
+	go build -o ./bin/canary ./tools/canary && ./bin/canary --root . --out status.json --csv status.csv
+
+canary-verify:
+	./bin/canary --root . --verify GAP_ANALYSIS.md --strict
+
+acceptance:
+	go test ./tools/canary/... -run TestAcceptance -v
+
 clean: 
 	rm -rf dist
 	rm -rf out
diff --git a/README.md b/README.md
@@ -51,3 +51,12 @@ Example: if a feature is marked `STATUS=IMPL` and has a `TEST=TestCANARY_REQ_GQL
 cd tools/canary
 go test -v
 ```
+
+## CANARY at a glance
+
+Policy excerpt (see `docs/CANARY_POLICY.md`). Example tokens:
+
+`CANARY: REQ=CBIN-101; FEATURE="ScannerCore"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_CBIN_101_Engine_ScanBasic; BENCH=BenchmarkCANARY_CBIN_101_Engine_Scan; OWNER=canary; UPDATED=2025-09-20`
+
+`CANARY: REQ=CBIN-102; FEATURE="VerifyGate"; ASPECT=CLI; STATUS=TESTED; TEST=TestCANARY_CBIN_102_CLI_Verify; BENCH=BenchmarkCANARY_CBIN_102_CLI_Verify; OWNER=canary; UPDATED=2025-09-20`
+
diff --git a/docs/CANARY_POLICY.md b/docs/CANARY_POLICY.md
@@ -0,0 +1,15 @@
+# CANARY Policy (Repo‑Wide)
+
+**Purpose.** Make every feature claim searchable and verifiable by linking requirements → code → tests → docs.
+
+## Token (single line, place at top of implementation files or relevant tests)
+`CANARY: REQ=CBIN-<###>; FEATURE="<name>"; ASPECT=<ASPECT>; STATUS=<STATUS>; TEST=<TestCANARY_CBIN_<###>_<Aspect>_<Short>>; BENCH=<BenchmarkCANARY_CBIN_<###>_<Aspect>_<Short>>; OWNER=<team-or-alias>; UPDATED=<YYYY-MM-DD>`
+
+- **ASPECT** ∈ ["API","CLI","Engine","Planner","Storage","Wire","Security","Docs","Decode","Encode","RoundTrip","Bench","FrontEnd","Dist"]
+- **STATUS** ∈ ["MISSING","STUB","IMPL","TESTED","BENCHED","REMOVED"]
+
+### Greps
+
+- `rg -n "CANARY:\s*REQ=CBIN-" src internal cmd tools`
+- `rg -n "TestCANARY_CBIN_" src internal cmd tools tests`
+- `rg -n "BenchmarkCANARY_CBIN_" src internal cmd tools tests`
diff --git a/internal/gen/prompts/prompts.go b/internal/gen/prompts/prompts.go
@@ -0,0 +1,3 @@
+package prompts
+
+// (deprecated placeholder intentionally left empty to avoid duplicate embeddings)
diff --git a/prompts/prompts.go b/prompts/prompts.go
@@ -0,0 +1,14 @@
+package prompts
+
+import _ "embed"
+
+//go:embed sys/init.md
+var Init string
+//go:embed sys/policy.md
+var Policy string
+//go:embed sys/requirements.md
+var Requirements string
+//go:embed sys/evaluate.md
+var Evaluate string
+
+func All() map[string]string { return map[string]string{"init": Init, "policy": Policy, "requirements": Requirements, "evaluate": Evaluate} }
diff --git a/status.csv b/status.csv
@@ -1,3 +1,4 @@
 req,feature,aspect,status,file,test,bench,owner,updated
-REQ-GQL-042,CDC/Streaming,API,STUB,internal/fixtures/file1.zig,tests/e2e_cdc.zig:TestCANARY_REQ_GQL_042_CDC_StartStop,,streaming,2025-09-20
-REQ-GQL-046,TDE,Storage,TESTED,internal/fixtures/file2.go,TestCANARY_REQ_GQL_046_KeyRotate,,security,2025-09-20
+CBIN-101,ScannerCore,Engine,BENCHED,tools/canary/main.go,TestCANARY_CBIN_101_Engine_ScanBasic,BenchmarkCANARY_CBIN_101_Engine_Scan,canary,2025-09-20
+CBIN-102,VerifyGate,CLI,BENCHED,tools/canary/verify.go,TestCANARY_CBIN_102_CLI_Verify,BenchmarkCANARY_CBIN_102_CLI_Verify,canary,2025-09-20
+CBIN-103,StatusJSON,API,BENCHED,tools/canary/status.go,TestCANARY_CBIN_103_API_StatusSchema,BenchmarkCANARY_CBIN_103_API_Emit,canary,2025-09-20
diff --git a/status.json b/status.json
@@ -1 +1 @@
-{"generated_at":"2025-09-20T21:01:03Z","requirements":[{"id":"CBIN-101","features":[{"feature":"ScannerCore","aspect":"Engine","status":"BENCHED","files":["main.go","sub/scan/cmd.go"],"tests":["TestCANARY_CBIN_101_Engine_ScanBasic"],"benches":["BenchmarkCANARY_CBIN_101_Engine_Scan"],"owner":"canary","updated":"2025-09-20"}]},{"id":"CBIN-102","features":[{"feature":"VerifyGate","aspect":"CLI","status":"BENCHED","files":["sub/verify/cmd.go","verify.go"],"tests":["TestCANARY_CBIN_102_CLI_Verify"],"benches":["BenchmarkCANARY_CBIN_102_CLI_Verify"],"owner":"canary","updated":"2025-09-20"}]},{"id":"CBIN-103","features":[{"feature":"StatusJSON","aspect":"API","status":"BENCHED","files":["status.go"],"tests":["TestCANARY_CBIN_103_API_StatusSchema"],"benches":["BenchmarkCANARY_CBIN_103_API_Emit"],"owner":"canary","updated":"2025-09-20"}]},{"id":"REQ-GQL-042","features":[{"feature":"CDC/Streaming","aspect":"API","status":"STUB","files":["internal/fixtures/file1.zig"],"tests":["tests/e2e_cdc.zig:TestCANARY_REQ_GQL_042_CDC_StartStop"],"benches":[],"owner":"streaming","updated":"2025-09-20"}]},{"id":"REQ-GQL-046","features":[{"feature":"TDE","aspect":"Storage","status":"TESTED","files":["internal/fixtures/file2.go"],"tests":["TestCANARY_REQ_GQL_046_KeyRotate"],"benches":[],"owner":"security","updated":"2025-09-20"}]}],"summary":{"by_status":{"BENCHED":3,"IMPL":0,"MISSING":0,"REMOVED":0,"STUB":1,"TESTED":1},"by_aspect":{"API":2,"CLI":1,"Engine":1,"Storage":1},"total_tokens":5,"unique_requirements":5}}
+{"generated_at":"2025-09-20T21:40:05Z","requirements":[{"id":"CBIN-101","features":[{"feature":"ScannerCore","aspect":"Engine","status":"BENCHED","files":["tools/canary/main.go"],"tests":["TestCANARY_CBIN_101_Engine_ScanBasic"],"benches":["BenchmarkCANARY_CBIN_101_Engine_Scan"],"owner":"canary","updated":"2025-09-20"}]},{"id":"CBIN-102","features":[{"feature":"VerifyGate","aspect":"CLI","status":"BENCHED","files":["tools/canary/verify.go"],"tests":["TestCANARY_CBIN_102_CLI_Verify"],"benches":["BenchmarkCANARY_CBIN_102_CLI_Verify"],"owner":"canary","updated":"2025-09-20"}]},{"id":"CBIN-103","features":[{"feature":"StatusJSON","aspect":"API","status":"BENCHED","files":["tools/canary/status.go"],"tests":["TestCANARY_CBIN_103_API_StatusSchema"],"benches":["BenchmarkCANARY_CBIN_103_API_Emit"],"owner":"canary","updated":"2025-09-20"}]}],"summary":{"by_status":{"BENCHED":3,"IMPL":0,"MISSING":0,"REMOVED":0,"STUB":0,"TESTED":0},"by_aspect":{"API":1,"CLI":1,"Engine":1},"total_tokens":3,"unique_requirements":3}}
diff --git a/sub/docs/cmd.go b/sub/docs/cmd.go
@@ -0,0 +1,83 @@
+package docs
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"text/template"
+	"time"
+
+	"github.com/spf13/cobra"
+	"go.codepros.org/canary/internal/core"
+	"go.codepros.org/canary/prompts"
+	"go.spyder.org/gen/cli"
+)
+
+// Cmd docs generate command (local template hydration only; AI call optional future).
+var Cmd = &cobra.Command{Use: "docs", Short: "generate documentation from embedded prompts", RunE: run}
+
+func init() {
+    if err := cli.SetArgs(Cmd.Flags(), "", Args()); err != nil { return }
+    f := Cmd.Flags()
+    f.String("out", "docs/generated", "output directory for generated docs")
+    f.Bool("print", false, "print generated outputs to stdout instead of writing files")
+    f.String("root", ".", "root to scan for status.json generation")
+    f.String("status", "", "optional existing status.json path (skip scan)")
+    f.String("model", "", "LLM model (optional; requires OPENAI_API_KEY)")
+}
+
+func run(cmd *cobra.Command, _ []string) error {
+    outDir, _ := cmd.Flags().GetString("out")
+    toStdout, _ := cmd.Flags().GetBool("print")
+    root, _ := cmd.Flags().GetString("root")
+    statusPath, _ := cmd.Flags().GetString("status")
+    model, _ := cmd.Flags().GetString("model")
+    if !toStdout { if err := os.MkdirAll(outDir, 0o755); err != nil { return err } }
+
+    var rep core.Report
+    var err error
+    if statusPath != "" {
+        b, rerr := os.ReadFile(statusPath)
+        if rerr != nil { return rerr }
+        if uerr := json.Unmarshal(b, &rep); uerr != nil { return uerr }
+    } else {
+        rep, err = core.Scan(core.ScanOptions{Root: root})
+        if err != nil { return err }
+    }
+
+    summaries := map[string]string{}
+    if model != "" {
+        // Lazy summarization placeholder (model integration would go here)
+        summaries["status"] = fmt.Sprintf("Status summary: %d requirements, %d tokens", rep.Summary.UniqueRequirements, rep.Summary.TotalTokens)
+    }
+
+    data := map[string]any{"Prompts": prompts.All(), "Status": rep, "Generated": time.Now().UTC().Format(time.RFC3339), "Summaries": summaries}
+    indexT := `# Generated Prompt Index\n\nGenerated: {{.Generated}}\n\n{{range $k,$v := .Prompts}}## {{$k}}\n\n<details><summary>show content</summary>\n\n{{$v}}\n\n</details>\n\n{{end}}\n---\n## Status Summary\nTotal Requirements: {{.Status.Summary.UniqueRequirements}}  Tokens: {{.Status.Summary.TotalTokens}}\n`
+    t, err := template.New("index").Parse(indexT)
+    if err != nil { return err }
+    outputs := map[string]string{}
+    for name, content := range prompts.All() { outputs[name+".md"] = content }
+    var buf []byte
+    b := &bytesBuffer{buf: &buf}
+    if err := t.Execute(b, data); err != nil { return err }
+    outputs["INDEX.md"] = string(b.Bytes())
+    bjson, _ := json.Marshal(rep)
+    outputs["status.json"] = string(bjson)
+    if toStdout {
+        for k, v := range outputs { fmt.Printf("--- %s ---\n%s\n", k, v) }
+        return nil
+    }
+    for name, content := range outputs { if err := os.WriteFile(filepath.Join(outDir, name), []byte(content), 0o644); err != nil { return err } }
+    fmt.Fprintf(os.Stderr, "generated %d docs -> %s\n", len(outputs), outDir)
+    return nil
+}
+
+// minimal buffer wrapper to avoid importing bytes unnecessarily (small).
+type bytesBuffer struct { buf *[]byte }
+func (b *bytesBuffer) Write(p []byte) (int, error) { *b.buf = append(*b.buf, p...); return len(p), nil }
+func (b *bytesBuffer) Bytes() []byte { return *b.buf }
+
+// args placeholder.
+var args cli.Args
+func Args() cli.Args { return args }
diff --git a/sub/report/cmd.go b/sub/report/cmd.go
@@ -3,14 +3,21 @@ package report
 import (
 	"encoding/json"
 	"errors"
+	"log/slog"
 	"os"
+	"sync"
 
 	"github.com/spf13/cobra"
+	"go.spyder.org/gen/cli"
 )
 
 var Cmd = &cobra.Command{Use: "report", Short: "print summary from status.json", RunE: Run}
 
 func init() {
+	if err := cli.SetArgs(Cmd.Flags(), "", Args()); err != nil {
+		slog.Error("error setting arguments", "error", err, "args", Args())
+		return
+	}
 	f := Cmd.Flags()
 	f.String("input", "status.json", "status.json to summarize")
 }
@@ -35,4 +42,13 @@ func Run(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
-// removed external cli arg reflection dependency
+//nolint:gochecknoglobals
+var once sync.Once
+
+//nolint:gochecknoglobals
+var args cli.Args
+
+func Args() cli.Args {
+	once.Do(func() { args = cli.Args{} })
+	return args
+}
diff --git a/sub/scan/cmd.go b/sub/scan/cmd.go
@@ -3,16 +3,22 @@ package scan
 import (
 	"log/slog"
 	"regexp"
+	"sync"
 
 	"github.com/spf13/cobra"
 	"go.codepros.org/canary/internal/cli/exitcodes"
 	"go.codepros.org/canary/internal/core"
+	"go.spyder.org/gen/cli"
 )
 
 // CANARY: REQ=CBIN-101; FEATURE="ScannerCore"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_CBIN_101_Engine_ScanBasic; BENCH=BenchmarkCANARY_CBIN_101_Engine_Scan; OWNER=canary; UPDATED=2025-09-20
 var Cmd = &cobra.Command{Use: "scan", Short: "scan the given paths for CANARY tokens", RunE: Run}
 
 func init() {
+	if err := cli.SetArgs(Cmd.Flags(), "", Args()); err != nil {
+		slog.Error("error setting arguments", "error", err, "args", Args())
+		return
+	}
 	f := Cmd.Flags()
 	f.String("root", ".", "root directory to scan")
 	f.String("out", "status.json", "output status.json path")
@@ -40,4 +46,13 @@ func Run(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
-// removed external cli arg reflection dependency
+//nolint:gochecknoglobals
+var once sync.Once
+
+//nolint:gochecknoglobals
+var args cli.Args
+
+func Args() cli.Args {
+	once.Do(func() { args = cli.Args{} })
+	return args
+}
diff --git a/sub/verify/cmd.go b/sub/verify/cmd.go
@@ -3,17 +3,23 @@ package verify
 import (
 	"log/slog"
 	"regexp"
+	"sync"
 	"time"
 
 	"github.com/spf13/cobra"
 	"go.codepros.org/canary/internal/cli/exitcodes"
 	"go.codepros.org/canary/internal/core"
+	"go.spyder.org/gen/cli"
 )
 
 // CANARY: REQ=CBIN-102; FEATURE="VerifyGate"; ASPECT=CLI; STATUS=TESTED; TEST=TestCANARY_CBIN_102_CLI_Verify; BENCH=BenchmarkCANARY_CBIN_102_CLI_Verify; OWNER=canary; UPDATED=2025-09-20
 var Cmd = &cobra.Command{Use: "verify", Short: "verify GAP claims & optional staleness", RunE: Run}
 
 func init() {
+	if err := cli.SetArgs(Cmd.Flags(), "", Args()); err != nil {
+		slog.Error("error setting arguments", "error", err, "args", Args())
+		return
+	}
 	f := Cmd.Flags()
 	f.String("root", ".", "root directory to scan before verification")
 	f.String("gap", "GAP_ANALYSIS.md", "gap analysis file to verify")
@@ -59,4 +65,13 @@ func Run(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
-// removed external cli arg reflection dependency
+//nolint:gochecknoglobals
+var once sync.Once
+
+//nolint:gochecknoglobals
+var args cli.Args
+
+func Args() cli.Args {
+	once.Do(func() { args = cli.Args{} })
+	return args
+}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+package prompts`
	`2`	`+`
	`3`	`+// (deprecated placeholder intentionally left empty to avoid duplicate embeddings)`