docs: post-v0.6 accuracy pass — Crush→Goose, arch update, bug backlog, godoc by jpleva91 · Pull Request #70 · AgentGuardHQ/shellforge

jpleva91 · 2026-03-28T06:28:47Z

Summary

Documentation accuracy pass following the v0.6.0/v0.6.1 releases that replaced Crush/Aider with Goose as the primary local execution driver.

Changes

README.md — Fix stale Crush references

Stack table: Execute | Crush → Execute | Goose (Block)
Architecture diagram: Agent Driver (Crush, ...) → Agent Driver (Goose, ...)
Core insight paragraph: updated Crush link → Goose link
CLI commands table: removed crush from driver list (not supported)
ASCII architecture diagram: Crush (Execution Engine) → Goose (Execution Engine)

docs/architecture.md — Update for v0.6.x

8-layer stack: replaced DeepAgents layer with Dagu (Orchestration), updated execution layer to Goose / OpenCode
OpenShell sandbox note corrected (was NVIDIA Landlock, now Docker/Colima on Mac)
Engine Architecture: Goose listed first as preferred local driver; OpenCode/DeepAgents remain as alternatives
Governance flow: added correction feedback loop step on denial (was showing abrupt block)
Data flow step 3: updated engine priority order

docs/roadmap.md — Add bug backlog section

Added Bug Backlog table with 7 open issues (#60–#69) to track known bugs before v1.0, including the governance bypass via malformed JSON (#62), zero test coverage (#60, #64, #68), fragile sed parsing (#67), and the normalizer prefix-match false positives (#63).

Go doc comments

Added godoc to exported functions that were missing them:

internal/governance/engine.go: Evaluate, GetTimeout
internal/logger/logger.go: Init, Close, Governance, ToolResult, Agent, ModelCall, Error, GetEntries
internal/tools/tools.go: Execute, FormatForPrompt

Verification

go build ./... passes (0 errors)
All Crush references removed from active documentation (roadmap retains historical v0.5.x entries as expected)

Governance Report

Check	Result
Branch	`agent/docs/post-v0.6-accuracy` ✓
Files changed	6 (50 insertions, 20 deletions) ✓
Force push	Never ✓
Production deploy	Not triggered ✓
Secrets in code	None ✓

…, godoc - README.md: Replace all stale Crush references with Goose (Block) in the stack table, architecture diagram, CLI commands table, and core insight. Crush was retired in v0.5.x; Goose is the current local execution driver. - docs/architecture.md: Update 8-layer stack to reflect v0.6.x reality — DeepAgents layer replaced by Dagu (orchestration), Crush→Goose (execution), OpenShell sandbox note updated. Engine Architecture section now lists Goose first, with OpenCode/DeepAgents as alternatives. Governance flow corrected to show correction feedback loop on denial. - docs/roadmap.md: Add Bug Backlog section cataloguing 7 open issues (#60-#69) covering test coverage gap, governance bypass via malformed JSON, fragile sed parsing in govern-shell.sh, silent log write failure, and dead code. - internal/governance/engine.go: Add godoc to Evaluate and GetTimeout. - internal/logger/logger.go: Add godoc to all 8 exported functions. - internal/tools/tools.go: Add godoc to Execute and FormatForPrompt. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jpleva91

Code Review — QA Pass

🟡 Duplicate/Conflicting Godoc Comments (`internal/tools/tools.go`)

PR adds new godoc lines below pre-existing comments, creating two conflicting descriptions for the same function:

// Execute runs a tool call through governance, then executes if allowed.  // ← pre-existing
// Execute evaluates the tool call against governance policy and, if allowed, runs it.  // ← added by this PR
// This is the fully governed path; use ExecuteDirect when governance is already checked.
func Execute(...)

// FormatForPrompt returns tool descriptions for the system prompt.  // ← pre-existing
// FormatForPrompt returns Markdown-formatted tool definitions for inclusion in a system prompt.  // ← added by this PR
func FormatForPrompt()

Go godoc treats the entire comment block as the doc string — having two sentences starting with the function name causes go doc output to show duplicated, contradictory descriptions. The original comment should be replaced, not supplemented.

Fix: Remove the original single-line comment on each function and keep only the new multi-line godoc.

🟡 Stale `crush` References in `cmd/shellforge/main.go` (Not Addressed by This PR)

This PR correctly updates all docs, but main.go still contains four stale Crush references that now contradict the updated documentation:

Line	Content
94	`Run a governed agent (claude, copilot, codex, gemini, crush)` — help text
519	`fmt.Fprintln(os.Stderr, "Available drivers: claude, copilot, codex, gemini, crush")` — runtime error message
783	`// Used by Crush fork to check actions before execution.` — code comment
809	`// Map Crush tool names to ShellForge tool names` — code comment

Since this PR is a "post-v0.6 accuracy pass" to align docs with the Goose transition, these should be included or tracked in a follow-up issue.

✅ Everything Else LGTM

go build ./... and go vet ./... pass cleanly
Roadmap bug backlog table is accurate
Architecture layer updates are correct
All Crush→Goose substitutions in docs are accurate

Copilot

Pull request overview

Documentation accuracy pass for the post-v0.6.x transition from Crush/Aider to Goose as the primary local execution driver, plus small GoDoc additions to exported APIs.

Changes:

Updated README + architecture docs to replace stale Crush references with Goose and refresh stack/flow descriptions.
Added a “Bug Backlog” section to the roadmap tracking known pre-v1.0 issues.
Added/expanded GoDoc comments for exported functions in governance, logger, and tools packages.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Replaces Crush with Goose in overview, stack table, CLI driver list, and architecture diagram.
docs/architecture.md	Updates 8-layer stack and engine/data-flow sections to reflect v0.6.x (Goose-first).
docs/roadmap.md	Adds a Bug Backlog table referencing open issues (#60–#69).
internal/governance/engine.go	Adds GoDoc for `Evaluate` and `GetTimeout`.
internal/logger/logger.go	Adds GoDoc for logging lifecycle and exported logging functions.
internal/tools/tools.go	Adds/expands GoDoc for governed tool execution and prompt formatting helpers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-28T10:45:31Z

docs/architecture.md

+4. **Native** (fallback) — built-in multi-turn loop with Ollama + tool calling

-The engine selection is automatic based on what's installed.
+The engine selection is automatic based on what's installed. Use `shellforge run goose` for local models, or `shellforge agent` for the native loop.


This text says engine selection is automatic based on what’s installed, but the CLI requires the user to explicitly choose a driver via shellforge run <driver> (it doesn’t auto-pick Goose/OpenCode/etc.). Please adjust the wording to match the current behavior (e.g., “ShellForge can run different engines; select one with shellforge run <driver>”).

Suggested change

The engine selection is automatic based on what's installed. Use `shellforge run goose` for local models, or `shellforge agent` for the native loop.

ShellForge can run different engines; select one explicitly with `shellforge run <driver>`. For example, use `shellforge run goose` for local models, or `shellforge agent` for the native loop.

Copilot · 2026-03-28T10:45:31Z

docs/architecture.md

 1. User invokes `./shellforge qa` (or agent, report, scan)
 2. CLI loads `agentguard.yaml` governance policy
-3. Detects available engine (OpenCode > DeepAgents > Native)
+3. Detects available engine (Goose > OpenCode > DeepAgents > Native)
 4. Engine sends prompt to Ollama (via RTK for token compression)


Data Flow step 3 describes automatic engine detection and a priority order (Goose > OpenCode > DeepAgents > Native). The current CLI flow doesn’t auto-select an engine; it runs the driver the user specifies. Please either describe the explicit selection (shellforge run goose|claude|...) or document where this auto-detection happens if it exists.

Copilot · 2026-03-28T10:45:31Z

internal/tools/tools.go

 // Execute runs a tool call through governance, then executes if allowed.
+// Execute evaluates the tool call against governance policy and, if allowed, runs it.
+// This is the fully governed path; use ExecuteDirect when governance is already checked.
 func Execute(engine *governance.Engine, agent, tool string, params map[string]string) Result {
 decision := engine.Evaluate(tool, params)


The doc comment for Execute is now redundant: the first line already provides a valid GoDoc summary, and the following two lines repeat the same information. Consider collapsing this into a single concise GoDoc block (keeping the extra detail about ExecuteDirect without duplicating the summary).

Suggested change

// Execute runs a tool call through governance, then executes if allowed.

// Execute evaluates the tool call against governance policy and, if allowed, runs it.

// This is the fully governed path; use ExecuteDirect when governance is already checked.

func Execute(engine *governance.Engine, agent, tool string, params map[string]string) Result {

decision := engine.Evaluate(tool, params)

// Execute runs a tool call through governance and, if allowed, executes it.

// This is the fully governed path; use ExecuteDirect when governance is already checked.

func Execute(engine *governance.Engine, agent, tool string, params map[string]string) Result {

decision := engine.Evaluate(tool, params)

decision := engine.Evaluate(tool, params)

Copilot · 2026-03-28T10:45:32Z

internal/tools/tools.go

@@ -224,6 +226,7 @@ return Result{Success: true, Output: output}
 }

 // FormatForPrompt returns tool descriptions for the system prompt.


FormatForPrompt has two consecutive GoDoc summary lines that both start with the function name and say essentially the same thing. Please remove the duplication and keep a single, precise summary (with any extra detail in subsequent sentences that don’t repeat the opener).

Suggested change

// FormatForPrompt returns tool descriptions for the system prompt.

Copilot · 2026-03-28T10:45:32Z

internal/logger/logger.go

 )

+// Init opens a JSONL log file under outputDir named "<agent>-<timestamp>.jsonl".
+// Must be called before any log functions; call Close when done.


The Init GoDoc says it “Must be called before any log functions,” but the logger functions still work without Init (they print to stdout and store in-memory entries; they just won’t write a JSONL file because logFile is nil). Please reword this to reflect the actual behavior (e.g., “Call Init to enable JSONL file logging; otherwise logs are stdout/in-memory only”).

Suggested change

// Must be called before any log functions; call Close when done.

// Call Init before logging to enable JSONL file output; otherwise logs are stdout/in-memory only. Call Close when done.

Copilot · 2026-03-28T10:45:32Z

internal/logger/logger.go

+// Governance logs a governance evaluation result to stdout and the JSONL log.
 func Governance(agent, tool string, params map[string]string, allowed bool, policyName, reason string) {
 status := "allow"


The Governance GoDoc says it logs to stdout and the JSONL log, but JSONL output only happens if Init has been called (logFile != nil). Consider clarifying that file logging is conditional so callers don’t assume a file is always written.

jpleva91 commented Mar 28, 2026

View reviewed changes

jpleva91 mentioned this pull request Mar 28, 2026

bug: stale crush references in cmd/shellforge/main.go contradict v0.6 Goose migration #74

Open

jpleva91 requested a review from Copilot March 28, 2026 10:43

jpleva91 merged commit 6f112cb into main Mar 28, 2026
7 checks passed

Copilot started reviewing on behalf of jpleva91 March 28, 2026 10:43 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: post-v0.6 accuracy pass — Crush→Goose, arch update, bug backlog, godoc#70

docs: post-v0.6 accuracy pass — Crush→Goose, arch update, bug backlog, godoc#70
jpleva91 merged 1 commit intomainfrom
agent/docs/post-v0.6-accuracy

jpleva91 commented Mar 28, 2026

Uh oh!

jpleva91 left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 28, 2026

Uh oh!

Copilot AI Mar 28, 2026

Uh oh!

Copilot AI Mar 28, 2026

Uh oh!

Copilot AI Mar 28, 2026

Uh oh!

Copilot AI Mar 28, 2026

Uh oh!

Copilot AI Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	The engine selection is automatic based on what's installed. Use `shellforge run goose` for local models, or `shellforge agent` for the native loop.
	ShellForge can run different engines; select one explicitly with `shellforge run <driver>`. For example, use `shellforge run goose` for local models, or `shellforge agent` for the native loop.

		@@ -224,6 +226,7 @@ return Result{Success: true, Output: output}
		}

		// FormatForPrompt returns tool descriptions for the system prompt.

	// Must be called before any log functions; call Close when done.
	// Call Init before logging to enable JSONL file output; otherwise logs are stdout/in-memory only. Call Close when done.

Conversation

jpleva91 commented Mar 28, 2026

Summary

Changes

README.md — Fix stale Crush references

docs/architecture.md — Update for v0.6.x

docs/roadmap.md — Add bug backlog section

Go doc comments

Verification

Governance Report

Uh oh!

jpleva91 left a comment

Choose a reason for hiding this comment

Code Review — QA Pass

🟡 Duplicate/Conflicting Godoc Comments (internal/tools/tools.go)

🟡 Stale crush References in cmd/shellforge/main.go (Not Addressed by This PR)

✅ Everything Else LGTM

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

🟡 Duplicate/Conflicting Godoc Comments (`internal/tools/tools.go`)

🟡 Stale `crush` References in `cmd/shellforge/main.go` (Not Addressed by This PR)