Documentation
¶
Overview ¶
Package sources — concrete IdeaSource implementations.
adr_questions: parses every ADR markdown under wiki/decisions/ for a "## Open questions" section and emits one Idea per numbered or bulleted item. Wiki is gitignored on this repo per operator policy, so a missing wiki/ directory is a silent no-op rather than an error — the source returns an empty slice and lets the orchestrator move on.
Package sources — bench_regression source.
Reads /tmp/clawtool-toolsearch-bench.tsv (the toolsearch BM25 rank-1 hit-rate fixture the autodev cron writes after each manifest tweak) and compares the latest run against a stored baseline at $XDG_CONFIG_HOME/clawtool/ideator/bench-baseline.json. A drop greater than DefaultRegressionThreshold (5pp) emits one Idea so the operator decides whether to chase the regression or roll the baseline forward.
Missing TSV → silent no-op (CI hasn't written one yet). Missing baseline → silent no-op (operator hasn't run `clawtool ideate --baseline-set` yet).
Package sources — ci_failures source.
Calls `gh run list --branch main --status failure --limit 10 --json databaseId,name,headSha,conclusion,event,createdAt` and emits one Idea per failed run. Falls back to a quiet no-op when the gh CLI isn't installed or unauthenticated — the spec calls this a cheap-on-fail signal, not a hard requirement.
Package sources — manifest_drift source.
Compares the manifest's hardcoded ToolSpec.Description against the *live* description each tool's Register fn emits via `mcp.WithDescription(...)`. Drift here is the v0.22.110 bug class: a hand-edit to one side leaves the search index ranking on stale prose. SyncDescriptionsFromRegistration auto-mirrors at boot, but this source guards against the inverse — someone removing the sync call or accidentally re-introducing the two hand-maintained copies.
Cycle note: this package can't import internal/tools/core (core registers IdeateRun / IdeateApply, which would import sources). The CLI / MCP edge injects the manifest builder via SetManifestBuilder before the orchestrator runs; when nothing is injected the source is a quiet no-op.
Package sources — todos source.
Walks repoRoot for *.go files (using a Go-native walker — no shell-out, no rg dependency) and emits one Idea per TODO / FIXME / XXX comment. DedupeKey is sha1(path + line + comment text) so the same comment surfaces the same id across runs even when other comments above it shift line numbers.
Index ¶
Constants ¶
const DefaultBenchTSV = "/tmp/clawtool-toolsearch-bench.tsv"
DefaultBenchTSV is the canonical TSV path the autodev cron writes. Columns: query, expected_top1, observed_top1, score.
const DefaultRegressionThreshold = 0.05
DefaultRegressionThreshold is the rank-1 hit-rate drop that promotes a TSV row into an Idea. 5pp is loud enough that the operator wants to know, quiet enough that single-test variance (one query per ideate cycle) doesn't trip it constantly.
Variables ¶
This section is empty.
Functions ¶
func DefaultBenchBaselinePath ¶
func DefaultBenchBaselinePath() string
DefaultBenchBaselinePath returns $XDG_CONFIG_HOME/clawtool/ideator/bench-baseline.json.
func SetDefaultManifestProvider ¶
func SetDefaultManifestProvider(p ManifestProvider)
SetDefaultManifestProvider lets the CLI / MCP edge inject a manifest builder. internal/cli/ideate.go calls this at init so every freshly-constructed ManifestDrift picks up the canonical builder; the function is safe to call multiple times.
Types ¶
type ADRQuestions ¶
type ADRQuestions struct{}
ADRQuestions implements IdeaSource. Construct via NewADRQuestions.
func NewADRQuestions ¶
func NewADRQuestions() *ADRQuestions
NewADRQuestions returns a ready-to-use ADR question miner.
func (ADRQuestions) Name ¶
func (ADRQuestions) Name() string
Name returns the canonical source name used by --source filters.
func (ADRQuestions) Scan ¶
Scan walks repoRoot/wiki/decisions/*.md. Missing directory is a silent no-op (wiki/ is gitignored on this repo). Each line under "## Open questions" that begins with `-`, `*`, or a numbered list marker becomes one Idea. The DedupeKey is sha1(adr-path + question text) so an unedited file produces stable IDs across runs.
type Baseline ¶
type Baseline struct {
HitRate float64 `json:"hit_rate"`
NumQueries int `json:"num_queries"`
WrittenAt string `json:"written_at"`
}
Baseline is the on-disk JSON shape the operator writes via `clawtool ideate --baseline-set`. HitRate is rank-1 (top-1 correct count / total queries).
func SaveBaseline ¶
SaveBaseline writes the current TSV's hit rate to the baseline path. CLI's `--baseline-set` calls this. Exposed at package level so the orchestrator + CLI share one writer.
type BenchRegression ¶
type BenchRegression struct {
// TSVPath overrides DefaultBenchTSV (tests inject tmpdir).
TSVPath string
// BaselinePath overrides the default baseline location.
BaselinePath string
// Threshold is the hit-rate drop (0..1) at which an Idea fires.
Threshold float64
}
BenchRegression implements IdeaSource for the BM25 baseline diff.
func NewBenchRegression ¶
func NewBenchRegression() *BenchRegression
NewBenchRegression returns a ready-to-use BM25 baseline-diff source with default paths and threshold.
func (BenchRegression) Name ¶
func (BenchRegression) Name() string
Name returns the canonical source name.
type CIFailures ¶
type CIFailures struct {
// Branch is the branch to inspect (default "main").
Branch string
// Limit caps how many failed runs gh returns (default 10).
Limit int
// GHBinary lets tests inject a stub binary; defaults to "gh".
GHBinary string
// Timeout caps the gh subprocess (default 10s).
Timeout time.Duration
}
CIFailures implements IdeaSource. Construct via NewCIFailures.
func NewCIFailures ¶
func NewCIFailures() *CIFailures
NewCIFailures returns a ready-to-use ci_failures miner.
type ManifestDrift ¶
type ManifestDrift struct {
// Provider returns the manifest to inspect. nil → silent no-op.
Provider ManifestProvider
}
ManifestDrift implements IdeaSource by diffing the manifest spec descriptions against what each Register fn registers live.
func NewManifestDrift ¶
func NewManifestDrift() *ManifestDrift
NewManifestDrift returns a ready-to-use manifest-drift detector. Provider must be wired separately via SetProvider or by direct field assignment; the CLI / MCP edge does this in internal/cli/ideate.go and internal/tools/core/ideator_tool.go (those layers can import core without creating a cycle).
func (ManifestDrift) Name ¶
func (ManifestDrift) Name() string
Name returns the canonical source name.
func (ManifestDrift) Scan ¶
Scan compares each registered spec description against the live `mcp.WithDescription` value. Mismatches surface as Ideas pointing the operator at SyncDescriptionsFromRegistration.
func (*ManifestDrift) SetProvider ¶
func (m *ManifestDrift) SetProvider(p ManifestProvider)
SetProvider lets a caller swap the manifest builder (tests use this to feed a hand-built manifest with deliberately drifted descriptions).
type ManifestProvider ¶
ManifestProvider returns the live MCP tool manifest. The CLI / MCP edge wraps core.BuildManifest into this shape so this package stays free of an import cycle.
type TODOs ¶
type TODOs struct {
// MaxIdeas caps the source's emit count so a repo with hundreds
// of TODOs doesn't drown the orchestrator's top-K. Default 50.
MaxIdeas int
// SkipDirs are directory names skipped during the walk
// (default: vendor, node_modules, .git, .clawtool, dist, bin).
SkipDirs []string
}
TODOs implements IdeaSource by mining TODO/FIXME/XXX comments from *.go files.
Source Files