stringer: Instructions file for Codex

AGENTS.md — Stringer

What is Stringer?

Stringer is a codebase archaeology tool that mines existing repositories to produce Beads-formatted issues. It solves the cold-start problem: when you adopt Beads on a mature codebase, agents wake up with zero context. Stringer gives them instant situational awareness by extracting actionable work items from signals already present in the repo.

Architecture

stringer/
├── cmd/stringer/           # CLI entrypoint
│   ├── main.go                 # cobra root setup
│   ├── root.go                 # root command, global flags
│   ├── scan.go                 # scan subcommand and flags
│   ├── report.go               # report subcommand
│   ├── context.go              # context subcommand
│   ├── docs.go                 # docs subcommand
│   ├── init.go                 # init subcommand (bootstrap stringer in a repo)
│   ├── config.go               # config get/set/list subcommands
│   ├── collectors.go           # collectors list/info subcommands (info shows thresholds, supports --json)
│   ├── baseline.go             # baseline create/suppress/list/remove/status subcommands (IDs: str- exact or sts- stable)
│   ├── baselinecheck.go        # baseline check <scan.json>: NEW (exit 4, with the suppress command) / RESOLVED (notice) vs the baseline, --accept/--prune, GitHub annotations; drives the self-scan gate (DR-027)
│   ├── mcp.go                  # mcp serve subcommand (MCP server)
│   ├── validate.go             # validate subcommand (JSONL validation)
│   ├── version.go              # version subcommand
│   ├── configwiring.go         # shared flag-to-config wiring
│   ├── exitcodes.go            # exit code constants
│   └── fs.go                   # filesystem helpers
├── internal/
│   ├── beads/              # Beads integration
│   │   ├── conventions.go      # Beads naming and format conventions
│   │   ├── dedup.go            # Beads-aware signal deduplication
│   │   └── reader.go           # Read existing beads from .beads/ directory
│   ├── bootstrap/          # stringer init bootstrapping
│   │   ├── bootstrap.go        # Bootstrap orchestration
│   │   ├── detect.go           # Project detection (language, framework, CI)
│   │   ├── config.go           # Generate .stringer.yaml defaults
│   │   ├── agentsmd.go         # Append stringer section to AGENTS.md
│   │   └── mcpjson.go          # Generate .mcp.json for Claude Code
│   ├── collector/          # Collector registry and interface
│   │   └── collector.go        # Register(), List(), Get(), Collector interface
│   ├── collectors/         # Signal extraction modules (one file per collector)
│   │   ├── todos.go            # TODO/FIXME/HACK/XXX/BUG/OPTIMIZE scanner; owns defaultExcludePatterns (vendor, node_modules, .beads, .stringer, .claude/worktrees, **/compiled/**, *.min.js, *.pb.go, zz_generated*.go, …) shared by all collectors; "!pattern" in user excludes opts a default back in; a leading "/" anchors a pattern at the walk root ("/api/**" skips api/ but not internal/api), used for nested workspace members (stringer-nxx.18)
│   │   ├── patterns_classify.go # shared file classification: isTestFile, isGeneratedFile (header markers in first 5 lines + minified heuristic: avg line > 400 chars over first 20 lines) used by every source-walking collector
│   │   ├── gitlog.go           # Reverts, high-churn files, stale branches; the commit walk is memoised in gitlogHistories and is repository-wide, so in a monorepo scan each workspace keeps only churn/revert signals for its own files (paths relative to the workspace, titles repository-relative) and only the first scanned workspace emits stale-branch signals; GitlogMetrics stay repository-wide (stringer-nxx.17)
│   │   ├── workspacescope.go   # workspaceScope: maps git-root-relative history paths into one workspace (rel to the git root, member list from CollectorOpts.WorkspaceMembers, nested members excluded) so stampWorkspace yields each repository-relative path exactly once; zero value = non-monorepo root
│   │   ├── historymemo.go      # historyMemo[K, V]: single-entry, process-wide memo for repository-wide walks — sync.Once per key so concurrent collectors share one walk, evicted when the key changes, failed walks not retained, waiter retries once if the walk it joined was cancelled by another caller's ctx; reset()/stats() for tests
│   │   ├── patterns*.go        # Large files, missing tests, low test coverage ratios (Go, JS/TS, Python, Ruby, Java, Kotlin, Rust, C#, PHP, Swift, Scala, Elixir).
│   │   │                       # patterns_testindex.go: repo-wide test index built once per scan — a source file counts as tested when any test file anywhere matches its stem
│   │   │                       # (<Name>Test(s)/Spec/Suite, Test<Name>, <name>_test/_spec, test_<name>, <Name>.test/.spec) or a <Name>Test(s) basename ends with it (NotificationDatabaseChannelTest → DatabaseChannel);
│   │   │                       # covers Maven src/main↔src/test mirrors (any module depth) and tests/<Project>.Tests/ sibling projects. patterns_testlookup.go: path-based fallbacks (same dir, parallel test roots, Rust inline tests).
│   │   │                       # DirectoryTestRatio.Ratio = CoveredFiles/SourceFiles using that same covered decision (not colocated test files), so mirrored trees get a real ratio; TestFiles keeps the colocated count.
│   │   │                       # low-test-ratio uses the same ratio. isTestOnlyDir (tests/, test/, spec/, __tests__/, benches/, Tests/ at any depth) drops test support files from both source and test counts (stringer-nxx.15).
│   │   │                       # patterns_classify.go: isNonSourceForTests excludes config (*.config.*, settings.py, dotfiles; under config/, configs/ or settings/ only yaml/json/toml/ini/xml/properties/cfg/conf files and Laravel-style PHP files whose first statement is `return [` — Go/Java/C#/Python packages named config stay source, stringer-nxx.16), data-only classes in PHP/C#/Java/Kotlin/Scala (Events/, Contracts/, Exceptions/, Dto(s)/, Models/,
│   │   │                       # Entities/, Interfaces/, *Exception/*Dto/*Interface), and doc/demo trees (docs_src/, docs/, examples/, extras/, samples/, tutorial*/ unless --include-demo-paths) from missing-tests AND DirectoryTestRatios
│   │   ├── lotteryrisk*.go     # Lottery risk: core, ownership math, review analysis, minimum-substance + shallow-history rules; the `git log --numstat` commit walk is memoised in numstatHistories keyed by (git dir, HEAD, depth, since) so workspaces of one scan share it (stringer-jfh.5) (lotteryrisk_substance.go: >=3 source files and >=100 blamed lines, static/fixture dir names skipped; shallow clones capped at 0.5 confidence and tagged shallow-history, DR-006 amendment) and its repository-relative paths are mapped through workspaceScope, directories of nested member workspaces are skipped, and blame/timestamp git commands run in the workspace directory so workspace-relative paths resolve (stringer-nxx.17)
│   │   ├── github.go           # GitHub issues, PRs, and review comments
│   │   ├── dephealth*.go       # Dependency health: 11 ecosystems (Go, npm, Cargo, Maven, Gradle, NuGet, PyPI, Packagist, SwiftPM, sbt, Hex); registry lookups run through `lookupEach` in dephealth_registry.go — a per-ecosystem worker pool (`registry_concurrency`, default 8) with a per-lookup deadline (`registry_timeout`, default 10s; was a fixed 30s), a 50-lookup cap that counts started lookups, input-order results, ctx cancellation between and during lookups, and timeouts counted in `DepHealthMetrics.TimedOut` and logged at WARN (stringer-ds4); every ecosystem client sends through `doRegistryRequest` in dephealth_http.go, which retries a 429 once (after `Retry-After`, capped at `registry_timeout`, else 1s) and a 5xx once (after 1s), never other 4xx, and returns non-200 as `*registryStatusError`; `lookupFailed` classifies failures (timed_out / rate_limited / server_error / not_found / other, GitHub rate limits via `githubLookupStatus`) into per-ecosystem `RegistryFailures` counters exposed as `DepHealthMetrics.RateLimited/ServerErrors/OtherErrors/NotFound/RegistryLookups` (+ `FailedLookups()`), `lookupEach` logs one WARN per ecosystem batch summarising failed lookups (404s stay at DEBUG), and the report Recommendations section notes failed lookups so an empty dependency section is not read as a clean bill of health (stringer-jfh.6); Maven/Gradle/sbt staleness reads repo1.maven.org maven-metadata.xml (release > latest > last non-SNAPSHOT version, lastUpdated in UTC) and falls back to search.maven.org solrsearch only on 404, malformed XML or a missing versioning block (stringer-jfh.3); version-specific checks (crates.io yanked, Hex retired, NuGet deprecated) report range floors as "… floor: name^x.y" at 0.6× confidence; Cargo.toml floors resolve through Cargo.lock and workspace members are skipped
│   │   ├── vuln*.go            # Vuln scanner: 11 ecosystems via OSV.dev (+ PHP, Swift, Scala, Elixir parsers); CVSS v3 base-score severity, npm dev/prod reachability, paginated OSV queries with partial-coverage accounting, versioned signal titles (DR-023); range/floor semantics (`PackageQuery.IsRange`/`Constraint`, "Vulnerable dependency floor" titles at 0.6× confidence), lockfile preference (package-lock.json, Cargo.lock, composer.lock in vuln_lock.go), workspace-member skipping (Cargo/npm workspaces, go.work, local replaces); NuGet Central Package Management (Directory.Packages.props PackageVersion/GlobalPackageReference, Directory.Build.props implicit references, $(Prop) interpolation, VersionOverride, packages.lock.json direct deps) resolved by nugetCentralResolver in vuln_nuget.go and shared with dephealth via parseCsprojQueries; Gradle version catalogs (gradle/*.versions.toml [versions]/[libraries] incl. version.ref and rich versions, Groovy ext maps such as gradle/dependencies.gradle with $versions.x / ${versions.x} interpolation in every coordinate segment incl. `_$versions.baseScala` artifact suffixes, `def` locals and the `substring(0, lastIndexOf("."))` base-version idiom, call-argument literals ignored; coordinates left with a placeholder or a dangling `_.`/`_`/`-` suffix are dropped at DEBUG in gradleQuery so malformed names never reach OSV or a registry, stringer-jfh.4), libs.x.y accessors and settings.gradle subproject build files resolved in vuln_gradle_catalog.go and shared with dephealth via parseGradleQueries
│   │   ├── configdrift.go       # Config drift: env var drift, dead keys, inconsistent defaults
│   │   ├── apidrift.go         # API drift: undocumented routes, unimplemented spec paths, stale versions
│   │   ├── docstale.go         # Doc staleness: stale docs, co-change drift, broken links (URI-scheme targets and fenced code blocks are skipped)
│   │   ├── docstale_links.go   # Broken-link resolver: detects static-site layouts (Hugo, MkDocs docs_dir, Docusaurus, Jekyll, mdBook, Sphinx, config-less Hugo _index.md trees) and resolves site-root links against content roots, pretty URLs/dir links to index/README/_index/.md sources, translations to their English original; skips URI schemes, fenced code, template placeholders ({x}, {{x}}, ${x}, <x>, %s, :param, [[x]]) and strips #fragment/?query (stringer-rd7, stringer-nxx.11)
│   │   ├── duplication*.go     # Code duplication: exact clones (Type 1) and near-clones (Type 2) via FNV-64a sliding window; duplication_merge.go merges overlapping windows into one signal per region with real line ranges, drops self-overlapping lists, and drops test-only groups under duplication_min_test_lines (DR-026); signal cap is per scanned workspace Test-only classification is directory-aware (isTestOnlyDir), so express-style test/*.js suites count as test code.
│   │   ├── coupling*.go        # Coupling: circular dependencies (Tarjan's SCC) and high fan-out modules via import graph; entry points/barrels auto-exempt, per-path exempt globs, default threshold 15 (DR-025). C# modules are declared namespaces (`namespace X;` or block form, directory-dots fallback) linked by `using`/`global using`/`using static`/alias directives
│   │   ├── complexity.go       # Complexity: AST-based for Go (cyclomatic/cognitive/nesting, floor 6); other languages get indentation-derived nesting-weighted scoring with string/comment stripping, a 0.5× JSX logical-op discount, and a floor of 12 (= confidence 0.5). Test code (shared isTestFile + test/tests/__tests__/spec/testdata dirs, JS describe/it callbacks, Rust #[test] fns) is skipped unless `include_tests: true`, then tagged `test-file` (DR-024). Regex languages: Python, JS/TS, Java, Rust, Ruby, PHP, Swift, Scala, Elixir, C# (methods/constructors; `foreach`, `??`, `?.` and ternary count; verbatim/interpolated strings stripped; expression-bodied members and `;`-terminated signatures have no body). A `langSpec.funcReject` regex vetoes keyword-led false matches where the language has keyword-less constructors
│   │   ├── complexity_go.go    # Go AST analysis: cyclomatic, cognitive, nesting depth via go/parser
│   │   ├── deadcode.go         # Dead code: regex symbol extraction (functions/types, 14 languages) then unreferenced-symbol detection; test files (shared isTestFile + test/tests/__tests__/spec/testdata dirs) only count as references unless `include_tests: true`, then their symbols are flagged tagged `test-file`; exported symbols of library repos are not reported by default (counted in `DeadCodeMetrics.PublicSuppressed`, one INFO log line); `include_public_api: true` restores them capped at 0.3 and tagged `public-api` (stringer-nxx.3, stringer-jfh.2)
│   │   ├── deadcode_csharp.go  # C# never-dead rules: runtime/host conventions (Main, Dispose, ToString, Equals, GetHashCode, Program, Startup, Configure*) and members under test-runner or ASP.NET attributes ([Fact], [Theory], [Test], [HttpGet], [Route], …); `private` members get the unexported confidence
│   │   ├── deadcode_skip.go    # Deadcode context rules: Rust brace-depth scan marks `impl Trait for T`/`trait` bodies (methods dispatched through the trait, never extracted) and #[cfg(test)] blocks; decorator/attribute/annotation-registered definitions (`@route`, `@Override`, `#[Route]`, `[Fact]`, `#[tokio::test]`; a plain-decorator allowlist such as `@property`/`#[inline]` does not count) are skipped; per-language visibility from the declaration line; library detection = manifest marker (Cargo `[lib]`, package.json main/exports w/o bin, pyproject `[project]` w/o scripts, composer `"type": "library"` or no `type` key — the composer default, setup.py) or no entry point (main.go, cmd/, bin/, src/main.rs, manage.py, app.py, artisan, Program.cs)
│   │   ├── deadcode_index.go   # Inverted identifier index for deadcode: each file is tokenized once into ASCII word runs (regexp `\b` semantics) and only declared symbol names are recorded as token → per-file counts, so each symbol check is a map lookup instead of a regexp over every file; names with non-word bytes (Elixir `Foo.Bar`, Ruby `valid?`) fall back to the regexp over index-bounded candidate files (stringer-nxx.1); predicate/bang names drop the trailing `\b` so `obj.valid?` counts as a reference
│   │   ├── githygiene.go       # Git hygiene: large binaries, merge conflicts, committed secrets, mixed line endings — tracked files only (git ls-files), full-scan fallback outside a repo
│   │   ├── secrets.go          # Secret detection: 24+ built-in patterns, custom patterns, allowlist, entropy detection; generic/JWT/entropy detectors are skipped in docs, examples, templates, comments and Python docstrings, placeholder values dropped, fixture values (`test key`) → 0.2, test-file hits capped at 0.3 (stringer-nxx.7)
│   │   └── duration.go         # Duration parsing helpers; gitSinceArg converts --git-since shorthand (90d/6m/1y) to an absolute RFC 3339 time for `git log --since`, which misreads the raw shorthand
│   ├── analysis/           # LLM-powered analysis
│   │   ├── cluster.go          # Signal clustering via LLM
│   │   ├── priority.go         # Priority inference via LLM
│   │   └── dependency.go       # Dependency detection via LLM
│   ├── config/             # .stringer.yaml config file support
│   │   ├── config.go           # Config and CollectorConfig structs
│   │   ├── yaml.go             # Load(), Write(), LoadRaw(), WriteFile()
│   │   ├── validate.go         # Validate() — multi-error validation
│   │   ├── merge.go            # Merge() — file config + CLI merge
│   │   ├── keypath.go          # Dot-notation key path navigation
│   │   └── global.go           # Global config (~/.config/stringer/)
│   ├── context/            # Context generation (stringer context)
│   │   ├── generator.go        # Context generation orchestration
│   │   ├── githistory.go       # Git history analysis for context
│   │   └── render_json.go      # JSON output for context
│   ├── docs/               # Docs generation (stringer docs)
│   │   ├── analyzer.go         # Repository analysis for docs
│   │   ├── detector.go         # Language/framework detection
│   │   ├── generator.go        # AGENTS.md generation
│   │   └── updater.go          # Update existing AGENTS.md preserving manual sections
│   ├── gitcli/             # Native git CLI wrapper (DR-011)
│   │   └── gitcli.go           # Shell out to git for blame and ownership
│   ├── llm/                # LLM provider abstraction
│   │   ├── provider.go         # Provider interface and registry
│   │   ├── anthropic.go        # Anthropic Claude provider
│   │   └── openai.go           # OpenAI-compatible provider
│   ├── log/                # Structured logging
│   │   └── log.go              # slog-based logging helpers
│   ├── mcpserver/          # MCP server for AI agent integration
│   │   ├── server.go           # Server creation and lifecycle
│   │   ├── tools.go            # Tool handlers: scan, report, context, docs
│   │   └── resolve.go          # Path resolution and input parsing
│   ├── output/             # Output formatters
│   │   ├── formatter.go        # Formatter interface and registry
│   │   ├── beads.go            # Beads JSONL writer (primary)
│   │   ├── json.go             # JSON with metadata envelope
│   │   ├── markdown.go         # Human-readable markdown summary
│   │   ├── sarif.go            # SARIF v2.1.0 output with suppressions + baseline comparison
│   │   ├── tasks.go            # Claude Code task format
│   │   └── signalid.go         # Shared deterministic signal ID (str-: source+kind+file+line+title); StableSignalID (sts-: source+kind+file+title with standalone numbers masked, survives line shifts and metric changes) and LookupSuppression (exact, then stable) for baselines (DR-027)
│   ├── pipeline/           # Scan orchestration
│   │   ├── pipeline.go         # New(), Run() — parallel execution via errgroup; Progress callbacks + heartbeat
│   │   ├── dedup.go            # Content-based signal deduplication
│   │   ├── enrich.go           # Cross-signal confidence boosting (co-location)
│   │   ├── baseline.go         # FilterSuppressed() — baseline suppression filtering by exact ID or stable key
│   │   └── validate.go         # ScanConfig validation
│   ├── redact/             # Secret redaction
│   │   └── redact.go           # Scrub sensitive patterns from signal content
│   ├── report/             # Report generation (stringer report)
│   │   ├── section.go          # Section registry and interface
│   │   ├── render.go           # Report rendering orchestration
│   │   ├── color.go            # Color-coded terminal output
│   │   ├── table.go            # Table formatting helpers
│   │   ├── lotteryrisk.go      # Lottery risk analysis section
│   │   ├── churn.go            # Code churn hotspots section
│   │   ├── todoage.go          # TODO age distribution section
│   │   ├── coverage.go         # Test coverage gaps section (Source / Covered / Tests / Ratio / Assessment; NO TESTS = CoveredFiles == 0)
│   │   ├── recommendations.go  # Actionable recommendations section
│   │   └── modulesummary.go    # Module health summary section
│   ├── baseline/           # Signal suppression state (baseline.json)
│   │   ├── baseline.go         # Load/Save/Lookup/AddOrUpdate/Remove for .stringer/baseline.json (saved one suppression per line)
│   │   └── rename.go           # Atomic rename helper (overridable for tests)
│   ├── signal/             # Domain types
│   │   └── signal.go           # RawSignal, ScanConfig, ScanResult, CollectorOpts
│   ├── state/              # Delta scan state persistence
│   │   └── state.go            # Load/Save/FilterNew/Build for .stringer/last-scan.json
│   ├── validate/           # JSONL validation for beads compatibility
│   │   └── validate.go         # Validate() — field-level JSONL validation
│   └── testable/           # Interfaces for test mock injection
│       ├── exec.go             # CommandExecutor interface
│       ├── exec_mock.go        # Mock command executor
│       ├── fs.go               # FileSystem interface
│       ├── mock_fs.go          # Mock filesystem
│       ├── git.go              # GitOpener interface
│       └── git_mock.go         # Mock git opener
├── test/
│   └── integration/        # End-to-end integration tests
├── eval/                   # Evaluation harness for stress-testing
├── testdata/
│   ├── fixtures/           # Test fixture repos
│   └── golden/             # Golden file outputs
├── docs/
│   ├── decisions/          # Decision records (see docs/decisions/)
│   ├── agent-integration.md    # MCP setup and tool reference
│   ├── branch-protection.md    # Branch protection rules
│   ├── competitive-analysis.md # Competitive landscape
│   └── release-strategy.md     # Versioning and release process
├── go.mod
├── go.sum
├── AGENTS.md               # You are here
├── README.md
├── LICENSE
└── CLAUDE.md