diff --git a/.gitignore b/.gitignore index 2baaffb..6fc5756 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,4 @@ Thumbs.db .uf/feedback/ .uf/muti-mind/artifacts/ .uf/mx-f/data/ +.uf/feedback/ diff --git a/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180509-jay-flowers.md b/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180509-jay-flowers.md new file mode 100644 index 0000000..1a6b44a --- /dev/null +++ b/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180509-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: gaze-multi-language-docs +author: jay-flowers +category: gotcha +created_at: 2026-08-23T18:05:09Z +identity: gaze-multi-language-docs-20260823T180509-jay-flowers +tier: draft +--- + +When running the /uf.unleash pipeline for documentation-only OpenSpec changes on the Unbound Force website, uncommitted work is lost across session breaks. The pipeline creates openspec artifacts and modifies content files but does not commit them until the final /uf.finale step. If a session is interrupted after implementation and code review pass but before committing, all work must be recreated from scratch. A mitigation pattern is to commit spec artifacts immediately after creation (with a "wip: openspec artifacts" commit) and commit implementation changes after each phase checkpoint. This prevents the full-recreation scenario that occurred during the gaze-multi-language-docs change, where the entire pipeline had to re-run because the branch was clean despite completing through code review. diff --git a/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180524-jay-flowers.md b/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180524-jay-flowers.md new file mode 100644 index 0000000..2757d8e --- /dev/null +++ b/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180524-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: gaze-multi-language-docs +author: jay-flowers +category: pattern +created_at: 2026-08-23T18:05:24Z +identity: gaze-multi-language-docs-20260823T180524-jay-flowers +tier: draft +--- + +During the spec review phase of the gaze-multi-language-docs OpenSpec change, the review council consistently identified cross-page consistency gaps that the original spec missed. The Guard agent found that content/docs/team/gaze-tester.md and content/docs/projects/_index.md still said "for Go" when the project page was being updated to "Go-native with multi-language support." The Tester agent identified that the tester guide's side effect count "30+ types" would become inconsistent with the project page's expanded "48+ types" taxonomy. These cross-page consistency findings were auto-fixed by adding additional tasks and spec requirements. The pattern: when updating a primary documentation page, always grep for the old framing across all related pages (team pages, index pages, guide pages) to ensure the narrative is consistent. The grep command `grep -r "for Go" content/` catches most of these. diff --git a/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180525-jay-flowers.md b/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180525-jay-flowers.md new file mode 100644 index 0000000..251f3c8 --- /dev/null +++ b/.uf/dewey/learnings/gaze-multi-language-docs-20260823T180525-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: gaze-multi-language-docs +author: jay-flowers +category: context +created_at: 2026-08-23T18:05:25Z +identity: gaze-multi-language-docs-20260823T180525-jay-flowers +tier: draft +--- + +When editing the homepage card badge in layouts/home.html for the Unbound Force website, the badge HTML pattern appears multiple times (once per project card). The edit must include enough surrounding context to uniquely identify the target card — specifically the parent anchor tag with the project-specific href. For example, to edit the Gaze badge, include the ` { - const els = JSON.parse(content).htmlElements; - return els.tags.concat(els.classes, els.ids); - }, - extensions: ['json'] - } - ], - dynamicAttributes: [ - 'aria-expanded', - 'data-bs-popper', - 'data-bs-target', - 'data-bs-theme', - 'data-dark-mode', - 'data-global-alert', - 'data-pane', - 'data-popper-placement', - 'data-sizes', - 'data-toggle-tab', - 'id', - 'size', - 'type' - ], - safelist: [ - 'active', - 'btn-clipboard', - 'clipboard', - 'disabled', - 'hidden', - 'modal-backdrop', - 'selected', - 'show', - 'img-fluid', - 'blur-up', - 'lazyload', - 'lazyloaded', - 'alert-link', - 'container-fw ', - 'container-lg', - 'container-fluid', - 'offcanvas-backdrop', - 'figcaption', - 'dt', - 'dd', - 'showing', - 'hiding', - 'page-item', - 'page-link', - 'not-content', - ...whitelister(['./assets/scss/**/*.scss', './node_modules/@thulite/doks-core/assets/scss/components/_code.scss', './node_modules/@thulite/doks-core/assets/scss/components/_expressive-code.scss', './node_modules/@thulite/doks-core/assets/scss/common/_syntax.scss']) - ] - }) - ] + plugins: [ + autoprefixer(), + purgecss({ + content: ["./hugo_stats.json"], + extractors: [ + { + extractor: (content) => { + const els = JSON.parse(content).htmlElements; + return els.tags.concat(els.classes, els.ids); + }, + extensions: ["json"], + }, + ], + dynamicAttributes: [ + "aria-expanded", + "data-bs-popper", + "data-bs-target", + "data-bs-theme", + "data-dark-mode", + "data-global-alert", + "data-pane", + "data-popper-placement", + "data-sizes", + "data-toggle-tab", + "id", + "size", + "type", + ], + safelist: [ + "active", + "btn-clipboard", + "clipboard", + "disabled", + "hidden", + "modal-backdrop", + "selected", + "show", + "img-fluid", + "blur-up", + "lazyload", + "lazyloaded", + "alert-link", + "container-fw ", + "container-lg", + "container-fluid", + "offcanvas-backdrop", + "figcaption", + "dt", + "dd", + "showing", + "hiding", + "page-item", + "page-link", + "not-content", + ...whitelister([ + "./assets/scss/**/*.scss", + "./node_modules/@thulite/doks-core/assets/scss/components/_code.scss", + "./node_modules/@thulite/doks-core/assets/scss/components/_expressive-code.scss", + "./node_modules/@thulite/doks-core/assets/scss/common/_syntax.scss", + ]), + ], + }), + ], }; diff --git a/content/blog/build-to-delete.md b/content/blog/build-to-delete.md index bc3b226..2898d32 100644 --- a/content/blog/build-to-delete.md +++ b/content/blog/build-to-delete.md @@ -18,7 +18,7 @@ Every component in an AI agent harness exists because someone believed the model These are bets on model limitations. Some of them are good bets that will remain true for years. Some of them are already becoming unnecessary. -Anthropic demonstrated this concretely: moving from Opus 4.5 to Opus 4.6, they stripped their sprint decomposition mechanism entirely because the newer model handled task breakdown reliably without external scaffolding. The harness component that was essential one model version ago became dead weight the next (as described in Yanli Liu, "Harness Engineering," *AI Advances*, Apr 2026). +Anthropic demonstrated this concretely: moving from Opus 4.5 to Opus 4.6, they stripped their sprint decomposition mechanism entirely because the newer model handled task breakdown reliably without external scaffolding. The harness component that was essential one model version ago became dead weight the next (as described in Yanli Liu, "Harness Engineering," _AI Advances_, Apr 2026). The article's advice is blunt: "build to delete." Design every harness component so it can be removed when the time comes. The hard part is not building the harness — it is having the discipline to prune it. @@ -40,7 +40,7 @@ These components will likely persist across multiple generations of model improv Other components exist specifically because current models have limitations. As those limitations diminish, the components become candidates for removal. -**The 5+ agent Divisor Council.** Five specialized review agents running in parallel, each with exclusive ownership boundaries. This is a powerful quality mechanism, but it is also heavy. As models improve at self-review — and early data from Opus 4.7 suggests they are (Liu, "Harness Engineering," *AI Advances*, Apr 2026) — the multi-agent review structure may be overkill. A future configuration might use three agents instead of five, or a single agent with computational-only validation. +**The 5+ agent Divisor Council.** Five specialized review agents running in parallel, each with exclusive ownership boundaries. This is a powerful quality mechanism, but it is also heavy. As models improve at self-review — and early data from Opus 4.7 suggests they are (Liu, "Harness Engineering," _AI Advances_, Apr 2026) — the multi-agent review structure may be overkill. A future configuration might use three agents instead of five, or a single agent with computational-only validation. **Detailed step-by-step instructions in agent personas.** Reading lists, checklists, ordered initialization sequences — these compensate for models that need explicit scaffolding to follow complex procedures. As models require less hand-holding, these instructions become noise rather than signal. @@ -61,6 +61,7 @@ The article recommends a simple protocol: after each model upgrade, test whether 3. **Delete if quality holds.** Not "deprecate" or "make optional" — delete. Dead harness weight is worse than no harness at all because it consumes context window, adds latency, and gives a false sense of security. Concrete experiments for Unbound Force: + - Run with 3 Divisor agents instead of 5 - Skip the Gaze feedback loop for a sprint - Remove Dewey knowledge retrieval from agent initialization diff --git a/content/blog/convention-packs.md b/content/blog/convention-packs.md index 1f9b37f..ca0798b 100644 --- a/content/blog/convention-packs.md +++ b/content/blog/convention-packs.md @@ -45,13 +45,13 @@ Each rule has three components: Unbound Force ships with packs for different domains: -| Pack | Domain | Example Rules | -|------|--------|---------------| -| `default.md` | All projects | Commit message format, PR conventions, error handling patterns | -| `go.md` | Go projects | `gofmt`, import organization, `Options`/`Result` pattern, `embed.FS` for assets | -| `content.md` | Content/docs | Frontmatter requirements, heading structure, link conventions | -| `typescript.md` | TypeScript projects | Formatting, type safety, module patterns | -| `severity.md` | Quality gates | CRAP score thresholds, coverage requirements, auto-fix policies | +| Pack | Domain | Example Rules | +| --------------- | ------------------- | ------------------------------------------------------------------------------- | +| `default.md` | All projects | Commit message format, PR conventions, error handling patterns | +| `go.md` | Go projects | `gofmt`, import organization, `Options`/`Result` pattern, `embed.FS` for assets | +| `content.md` | Content/docs | Frontmatter requirements, heading structure, link conventions | +| `typescript.md` | TypeScript projects | Formatting, type safety, module patterns | +| `severity.md` | Quality gates | CRAP score thresholds, coverage requirements, auto-fix policies | ## The Extension Pattern @@ -87,7 +87,7 @@ The structure of convention packs — numbered rules, explicit severity, concret ## Packs as Harness Templates -ThoughtWorks' agent taxonomy includes the concept of "harness templates" — reusable patterns that can be deployed across projects to establish consistent agent behavior (as described in Yanli Liu, "Harness Engineering," *AI Advances*, Apr 2026). Convention packs are a direct implementation of this concept. +ThoughtWorks' agent taxonomy includes the concept of "harness templates" — reusable patterns that can be deployed across projects to establish consistent agent behavior (as described in Yanli Liu, "Harness Engineering," _AI Advances_, Apr 2026). Convention packs are a direct implementation of this concept. The key insight is that coding standards are a property of the organization, not the project. An organization that values error chain preservation values it in every Go project, not just the one where someone wrote it down. Convention packs make organizational standards portable, versioned, and consistently deployed — the same way a CI workflow template ensures every project runs the same quality checks. diff --git a/content/blog/five-principles-every-ai-agent-harness-discovers.md b/content/blog/five-principles-every-ai-agent-harness-discovers.md index db3f5d1..684dd75 100644 --- a/content/blog/five-principles-every-ai-agent-harness-discovers.md +++ b/content/blog/five-principles-every-ai-agent-harness-discovers.md @@ -16,13 +16,13 @@ contributors: ["Unbound Force"] Three independent teams — OpenAI, Anthropic, and ThoughtWorks — each spent months building AI agent harnesses. They started from different assumptions, used different architectures, and optimized for different goals. They arrived at the same five conclusions. -Yanli Liu documented this convergence in ["Harness Engineering: What Every AI Engineer Needs to Know in 2026" (*AI Advances*, Apr 2026)](https://ai.gopubby.com/harness-engineering-what-every-ai-engineer-needs-to-know-in-2026-0ab649e5686a), cataloging the principles that every team discovers when they move from toy demos to production-grade agent systems. The article has 1.7K claps for a reason: if you have built an agent harness, you recognize every finding immediately. +Yanli Liu documented this convergence in ["Harness Engineering: What Every AI Engineer Needs to Know in 2026" (_AI Advances_, Apr 2026)](https://ai.gopubby.com/harness-engineering-what-every-ai-engineer-needs-to-know-in-2026-0ab649e5686a), cataloging the principles that every team discovers when they move from toy demos to production-grade agent systems. The article has 1.7K claps for a reason: if you have built an agent harness, you recognize every finding immediately. Unbound Force implements all five principles. In several cases, it goes further than any of the three teams Liu describes. This post walks through each principle with concrete evidence from the codebase. ## Principle 1: Context Beats Instructions -**The finding**: Showing the agent real file paths, real code patterns, and real progress consistently outperforms abstract instructions. OpenAI learned to "give a map, not a manual." Anthropic built structured feature lists. ThoughtWorks calls it "feedforward" (Liu, "Harness Engineering," *AI Advances*, Apr 2026). +**The finding**: Showing the agent real file paths, real code patterns, and real progress consistently outperforms abstract instructions. OpenAI learned to "give a map, not a manual." Anthropic built structured feature lists. ThoughtWorks calls it "feedforward" (Liu, "Harness Engineering," _AI Advances_, Apr 2026). **How Unbound Force implements it**: Through three layers of context, each serving a different purpose. @@ -36,7 +36,7 @@ Most teams implement one of these layers. Unbound Force stacks all three: static ## Principle 2: Planning and Execution Must Be Separated -**The finding**: Every team discovered that letting an agent plan and execute in the same pass produces unreliable output. The planning step must be separate, with its output reviewed before implementation begins (Liu, "Harness Engineering," *AI Advances*, Apr 2026). +**The finding**: Every team discovered that letting an agent plan and execute in the same pass produces unreliable output. The planning step must be separate, with its output reviewed before implementation begins (Liu, "Harness Engineering," _AI Advances_, Apr 2026). **How Unbound Force implements it**: Through an 8-phase pipeline with hard gates between phases. @@ -47,6 +47,7 @@ constitution → specify → clarify → plan → tasks → analyze → checklis This is not a suggestion — it is enforced. If an agent attempts to write code during the planning phase, it triggers a process violation and must stop. The phase boundaries are structural: you cannot plan before you specify, cannot create tasks before you plan, and cannot implement before spec review passes. The enforcement mechanisms are concrete: + - Branch naming conventions gate pipeline entry - All spec artifacts must be committed before implementation begins (the Spec Commit Gate) - The [/uf.unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) command has six defined exit points where human judgment is required @@ -55,7 +56,7 @@ Liu's article describes plan/execute separation as a two-phase concern. Unbound ## Principle 3: Feedback Loops Are Non-Negotiable -**The finding**: All three teams agree that a system without a feedback mechanism is "just a prompt with extra steps." They disagree on whether feedback should come from automated tests, another LLM, or both. ThoughtWorks says: use both, layered — computational feedback first (fast, cheap, deterministic), inferential feedback second (slow, expensive, semantic) (Liu, "Harness Engineering," *AI Advances*, Apr 2026). +**The finding**: All three teams agree that a system without a feedback mechanism is "just a prompt with extra steps." They disagree on whether feedback should come from automated tests, another LLM, or both. ThoughtWorks says: use both, layered — computational feedback first (fast, cheap, deterministic), inferential feedback second (slow, expensive, semantic) (Liu, "Harness Engineering," _AI Advances_, Apr 2026). **How Unbound Force implements it**: Both, layered — exactly what ThoughtWorks recommends. @@ -69,7 +70,7 @@ The Anthropic finding — separate the doer from the judge — is fully realized ## Principle 4: One Thing at a Time -**The finding**: Agents that try to do too much at once lose coherence. Forced incrementalism — where the agent completes one unit of work before starting the next — is universal across every successful implementation (Liu, "Harness Engineering," *AI Advances*, Apr 2026). +**The finding**: Agents that try to do too much at once lose coherence. Forced incrementalism — where the agent completes one unit of work before starting the next — is universal across every successful implementation (Liu, "Harness Engineering," _AI Advances_, Apr 2026). **How Unbound Force implements it**: At two levels. @@ -79,7 +80,7 @@ At the specification level, the 8-phase pipeline enforces incrementalism on the ## Principle 5: The Codebase Is the Documentation -**The finding**: Nobody maintains a separate knowledge base for the agent. The repository is the single source of truth. Teams that invest in code organization, clear module boundaries, and embedded documentation get better agent performance for free (Liu, "Harness Engineering," *AI Advances*, Apr 2026). +**The finding**: Nobody maintains a separate knowledge base for the agent. The repository is the single source of truth. Teams that invest in code organization, clear module boundaries, and embedded documentation get better agent performance for free (Liu, "Harness Engineering," _AI Advances_, Apr 2026). **How Unbound Force implements it**: All agent context lives in the repository. diff --git a/content/blog/gateway-credentials.md b/content/blog/gateway-credentials.md index 7b0bfe1..27201ff 100644 --- a/content/blog/gateway-credentials.md +++ b/content/blog/gateway-credentials.md @@ -36,11 +36,11 @@ uf gateway --detach # start the proxy in the background The gateway auto-detects your provider from environment variables: -| Priority | Provider | Detection | -|----------|----------|-----------| -| 1 | **Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1` + `ANTHROPIC_VERTEX_PROJECT_ID` | -| 2 | **Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | -| 3 | **Anthropic** | `ANTHROPIC_API_KEY` | +| Priority | Provider | Detection | +| -------- | ------------- | ---------------------------------------------------------- | +| 1 | **Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1` + `ANTHROPIC_VERTEX_PROJECT_ID` | +| 2 | **Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | +| 3 | **Anthropic** | `ANTHROPIC_API_KEY` | Once running, any container on the host can call `http://localhost:53147` with a dummy token. The gateway intercepts the request, injects real credentials, translates the request format for the upstream provider, and forwards it. The container's code never changes regardless of which provider you use. @@ -80,14 +80,14 @@ OAuth tokens and session credentials expire. If your agent runs for 2 hours, the ## Before and After -| Aspect | Before Gateway | With Gateway | -|--------|---------------|--------------| -| **Env vars forwarded** | 4-6 (provider-specific) | 2 (`ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`) | -| **Credential mounts** | gcloud dir, service account keys, AWS config | None | -| **SDK dependencies** | AWS SDK, gcloud CLI inside container | None | -| **Token management** | Container-side refresh logic | Host-side, automatic | -| **Provider switching** | Rebuild container config | Change host env vars, restart gateway | -| **Container image** | Provider-specific variants | Single universal image | +| Aspect | Before Gateway | With Gateway | +| ---------------------- | -------------------------------------------- | --------------------------------------------- | +| **Env vars forwarded** | 4-6 (provider-specific) | 2 (`ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`) | +| **Credential mounts** | gcloud dir, service account keys, AWS config | None | +| **SDK dependencies** | AWS SDK, gcloud CLI inside container | None | +| **Token management** | Container-side refresh logic | Host-side, automatic | +| **Provider switching** | Rebuild container config | Change host env vars, restart gateway | +| **Container image** | Provider-specific variants | Single universal image | The container sees the same two environment variables regardless of whether you use Vertex AI, Bedrock, or Anthropic direct. Switching providers is a host-side configuration change — the container image and agent code remain identical. diff --git a/content/blog/gaze-in-practice.md b/content/blog/gaze-in-practice.md index 063301c..272423d 100644 --- a/content/blog/gaze-in-practice.md +++ b/content/blog/gaze-in-practice.md @@ -21,6 +21,7 @@ This walkthrough answers that question. We ran Gaze against [gcal-organizer](htt The report below was generated using `/gaze` in OpenCode — the full report mode that combines CRAP analysis, contract quality assessment, side effect classification, and overall health scoring. Every number is reproduced exactly as Gaze produced it. **Report metadata:** + - **Project**: github.com/jflowers/gcal-organizer - **Branch**: 008-decision-extraction - **Gaze Version**: v1.2.3 @@ -31,13 +32,13 @@ The report below was generated using `/gaze` in OpenCode — the full report mod The CRAP (Change Risk Anti-Patterns) summary provides aggregate metrics across all functions in the module. -| Metric | Value | -|--------|------:| -| Total functions analyzed | 137 | -| Average complexity | 4.9 | -| Average line coverage | 26.2% | -| Average CRAP score | 29.7 | -| CRAPload | 40 (functions ≥ threshold 15) | +| Metric | Value | +| ------------------------ | ----------------------------: | +| Total functions analyzed | 137 | +| Average complexity | 4.9 | +| Average line coverage | 26.2% | +| Average CRAP score | 29.7 | +| CRAPload | 40 (functions ≥ threshold 15) | ### What This Tells Us @@ -49,13 +50,13 @@ The average CRAP score of 29.7 is inflated by the tail — a handful of very com Gaze surfaces the functions with the highest individual CRAP scores — the specific places where change risk is concentrated. -| Function | CRAP | Complexity | Coverage | File | -|----------|-----:|----------:|---------:|------| -| (\*Service).CreateDecisionsTab | 650.0 | 25 | 0.0% | internal/docs/service.go:460 | -| runBrowserScript | 342.0 | 18 | 0.0% | cmd/gcal-organizer/assign_tasks.go:237 | -| loadDotEnv | 240.0 | 15 | 0.0% | cmd/gcal-organizer/main.go:382 | -| (\*Service).ListMeetingDocuments | 210.0 | 14 | 0.0% | internal/drive/service.go:113 | -| (\*Organizer).printSummary | 156.0 | 12 | 0.0% | internal/organizer/organizer.go:227 | +| Function | CRAP | Complexity | Coverage | File | +| -------------------------------- | ----: | ---------: | -------: | -------------------------------------- | +| (\*Service).CreateDecisionsTab | 650.0 | 25 | 0.0% | internal/docs/service.go:460 | +| runBrowserScript | 342.0 | 18 | 0.0% | cmd/gcal-organizer/assign_tasks.go:237 | +| loadDotEnv | 240.0 | 15 | 0.0% | cmd/gcal-organizer/main.go:382 | +| (\*Service).ListMeetingDocuments | 210.0 | 14 | 0.0% | internal/drive/service.go:113 | +| (\*Organizer).printSummary | 156.0 | 12 | 0.0% | internal/organizer/organizer.go:227 | ### What This Tells Us @@ -69,18 +70,18 @@ The next three functions (`runBrowserScript`, `loadDotEnv`, `ListMeetingDocument This is where Gaze goes beyond traditional CRAP. The GazeCRAP quadrant places each function on a 2x2 grid comparing its traditional CRAP score (complexity + line coverage) against its GazeCRAP score (complexity + contract coverage). For a deeper explanation of this distinction, see [Why Contract Coverage](/blog/why-contract-coverage/). -| Quadrant | Count | Meaning | -|----------|------:|---------| -| 🟢 Q1 — Safe | 12 | Low complexity, high contract coverage | -| 🟡 Q2 — Complex But Tested | 0 | High complexity, contracts verified | -| 🔴 Q4 — Dangerous | 2 | Complex AND contracts not adequately verified | -| ⚪ Q3 — Needs Tests | 3 | Simple but underspecified | +| Quadrant | Count | Meaning | +| -------------------------- | ----: | --------------------------------------------- | +| 🟢 Q1 — Safe | 12 | Low complexity, high contract coverage | +| 🟡 Q2 — Complex But Tested | 0 | High complexity, contracts verified | +| 🔴 Q4 — Dangerous | 2 | Complex AND contracts not adequately verified | +| ⚪ Q3 — Needs Tests | 3 | Simple but underspecified | **GazeCRAPload**: 5 (functions ≥ threshold 15) — The 2 Q4 functions (`SyncCalendarAttachments` at GazeCRAP 1482 and `OrganizeDocuments` at 306) have decent line coverage but 0% contract coverage, meaning their side effects are tested incidentally rather than intentionally. The 3 Q3 functions need contract-level assertions added to existing tests, not new test files. ### What This Tells Us -The quadrant distribution reveals something the raw CRAP scores cannot: the difference between functions that are tested and functions that are *verified*. +The quadrant distribution reveals something the raw CRAP scores cannot: the difference between functions that are tested and functions that are _verified_. 12 functions land in Q1 (Safe) — these are the functions where both complexity and contract obligations are under control. Zero functions are in Q2 (Complex But Tested), which means there are no complex functions where contracts are being intentionally verified. This is a gap. @@ -126,19 +127,19 @@ The health assessment combines all dimensions into a single scorecard with lette ### Summary Scorecard -| Dimension | Grade | Details | -|-----------|-------|---------| -| CRAPload | 🔴 D | 40/137 functions (29.2%) above threshold | -| GazeCRAPload | 🟢 A- | 5/17 analyzed functions above threshold | -| Avg Line Coverage | 🔴 D | 26.2% — 101 of 137 functions have 0% coverage | -| Contract Coverage | 🟡 C | 52.9% avg across 17 quality-analyzed functions | -| Complexity | 🟢 B+ | Average 4.9, but 40 functions exceed threshold | +| Dimension | Grade | Details | +| ----------------- | ----- | ---------------------------------------------- | +| CRAPload | 🔴 D | 40/137 functions (29.2%) above threshold | +| GazeCRAPload | 🟢 A- | 5/17 analyzed functions above threshold | +| Avg Line Coverage | 🔴 D | 26.2% — 101 of 137 functions have 0% coverage | +| Contract Coverage | 🟡 C | 52.9% avg across 17 quality-analyzed functions | +| Complexity | 🟢 B+ | Average 4.9, but 40 functions exceed threshold | ### What This Tells Us The scorecard paints a nuanced picture. Complexity gets a B+ — the project is not over-engineered, and most individual functions are reasonably simple. But line coverage at 26.2% (with 101 functions at 0%) earns a D, and CRAPload at 29.2% confirms that the combination of untested + complex code is widespread. -The interesting contrast is between the two CRAP dimensions: traditional CRAPload gets a D (40 functions above threshold across all 137), but GazeCRAPload gets an A- (only 5 of the 17 quality-analyzed functions above threshold). This suggests that the functions which *do* have tests are generally well-tested at the contract level. The problem is not test quality — it is test *quantity*. Large swaths of the codebase have no tests at all. +The interesting contrast is between the two CRAP dimensions: traditional CRAPload gets a D (40 functions above threshold across all 137), but GazeCRAPload gets an A- (only 5 of the 17 quality-analyzed functions above threshold). This suggests that the functions which _do_ have tests are generally well-tested at the contract level. The problem is not test quality — it is test _quantity_. Large swaths of the codebase have no tests at all. Contract Coverage at 52.9% (C grade) across the 17 analyzed functions means about half of the contractual side effects are being verified. For the functions that have tests, there is room to tighten the assertions, but it is not catastrophic. diff --git a/content/blog/sandbox-isolation.md b/content/blog/sandbox-isolation.md index b302084..5ab29c0 100644 --- a/content/blog/sandbox-isolation.md +++ b/content/blog/sandbox-isolation.md @@ -126,14 +126,14 @@ uf sandbox attach # reconnect to a running sandbox's TUI The sandbox provides multiple isolation layers: -| Property | Description | -|----------|-------------| -| **Rootless Podman** | Container runs without root privileges on the host | -| **Read-only mounts** | Isolated mode mounts the project read-only (default) | -| **No push credentials** | Git push credentials are never forwarded to the container | -| **Resource limits** | Memory (default 8g) and CPU (default 4) limits prevent runaway processes | -| **SELinux** | Auto-detects SELinux and applies `:Z` volume labels on enforcing systems | -| **Non-root user** | Container runs as UID 1000 (non-root) inside the namespace | +| Property | Description | +| ----------------------- | ------------------------------------------------------------------------ | +| **Rootless Podman** | Container runs without root privileges on the host | +| **Read-only mounts** | Isolated mode mounts the project read-only (default) | +| **No push credentials** | Git push credentials are never forwarded to the container | +| **Resource limits** | Memory (default 8g) and CPU (default 4) limits prevent runaway processes | +| **SELinux** | Auto-detects SELinux and applies `:Z` volume labels on enforcing systems | +| **Non-root user** | Container runs as UID 1000 (non-root) inside the namespace | The agent can read your code but cannot: modify your files (isolated mode), push to your remote, consume unbounded resources, or escalate privileges. The blast radius of any agent mistake is contained to a disposable container. diff --git a/content/blog/the-8-phase-pipeline.md b/content/blog/the-8-phase-pipeline.md index 05bbdd9..1bf6402 100644 --- a/content/blog/the-8-phase-pipeline.md +++ b/content/blog/the-8-phase-pipeline.md @@ -14,7 +14,7 @@ contributors: ["Unbound Force"] ## The Two-Phase Illusion -Every team building AI agent workflows discovers the same thing: letting an agent plan and execute in the same pass produces unreliable output. The planning step must be separate, with its output reviewed before implementation begins. OpenAI, Anthropic, and ThoughtWorks all arrived at this conclusion independently (Yanli Liu, "Harness Engineering," *AI Advances*, Apr 2026). +Every team building AI agent workflows discovers the same thing: letting an agent plan and execute in the same pass produces unreliable output. The planning step must be separate, with its output reviewed before implementation begins. OpenAI, Anthropic, and ThoughtWorks all arrived at this conclusion independently (Yanli Liu, "Harness Engineering," _AI Advances_, Apr 2026). So you separate plan from execute. Two phases. Problem solved. diff --git a/content/blog/why-your-ai-code-reviewer-cannot-have-write-access.md b/content/blog/why-your-ai-code-reviewer-cannot-have-write-access.md index 72550ec..e206b43 100644 --- a/content/blog/why-your-ai-code-reviewer-cannot-have-write-access.md +++ b/content/blog/why-your-ai-code-reviewer-cannot-have-write-access.md @@ -16,7 +16,7 @@ contributors: ["Unbound Force"] When the same AI agent writes code and reviews it, the review is compromised. The agent has context about why it made each decision. It remembers the trade-offs it considered. It is, in the most literal sense, reviewing its own homework. -Anthropic discovered this when building their multi-agent systems: agents tasked with both producing and evaluating work would "confidently praise broken implementations" (as described in Yanli Liu, "Harness Engineering," *AI Advances*, Apr 2026). The agent was not lying — it genuinely believed the code was correct because it had rationalized each decision during implementation. +Anthropic discovered this when building their multi-agent systems: agents tasked with both producing and evaluating work would "confidently praise broken implementations" (as described in Yanli Liu, "Harness Engineering," _AI Advances_, Apr 2026). The agent was not lying — it genuinely believed the code was correct because it had rationalized each decision during implementation. The obvious fix is to use a separate agent for review. But separation is not enough if the review agent can modify what it reviews. A reviewer with write access is not a reviewer — it is a second developer. The moment the reviewer can "fix" an issue instead of reporting it, two things happen: the fix bypasses the normal implementation pipeline (no tests, no spec alignment check), and the reviewer loses objectivity because it is now invested in the code it touched. @@ -49,7 +49,7 @@ Structural doer/judge separation is one part of a larger feedback architecture. **Layer 2 — Inferential feedback.** The Divisor Council — five or more specialized review agents running in parallel. Each agent evaluates from a different perspective: the Guard checks for intent drift, the Architect reviews structural integrity, the Adversary stress-tests for security and edge cases, the Tester evaluates test quality, and the SRE assesses operational readiness. Each agent has explicit "Out of Scope" sections to prevent overlap. -This layering follows a principle identified independently by multiple teams building AI agent systems: use computational feedback first, then inferential feedback (ThoughtWorks' terminology, as described in Liu, "Harness Engineering," *AI Advances*, Apr 2026). Deterministic checks are cheaper and more reliable; inferential review is powerful but expensive. Running them in order maximizes the value of each layer. +This layering follows a principle identified independently by multiple teams building AI agent systems: use computational feedback first, then inferential feedback (ThoughtWorks' terminology, as described in Liu, "Harness Engineering," _AI Advances_, Apr 2026). Deterministic checks are cheaper and more reliable; inferential review is powerful but expensive. Running them in order maximizes the value of each layer. ## The Three-Iteration Cap @@ -64,6 +64,7 @@ This cap also prevents a subtle failure mode: the implementation agent and revie If you are building AI code review into your workflow, the enforcement model matters more than the review prompt. A sophisticated review prompt with full write access produces worse outcomes than a simple review prompt with structural separation. The checklist: + - **Separate the agents.** The agent that writes code and the agent that reviews code must be different instances with different context. - **Remove write access from reviewers.** Not "do not write" — actually remove the tools. No write, no edit, no bash. - **Layer your feedback.** Run deterministic checks first, semantic review second. Do not waste inferential review on code that fails to compile. diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index cef3c1b..aded89d 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -20,7 +20,7 @@ Unbound Force is built on four complementary tools that form a layered stack: | Layer | Tool | What It Does | | ---------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| **CLI** | [`uf`](/docs/reference/cli/) | Project scaffolding, environment setup, health checks, configuration, sandboxed execution, LLM gateway. | +| **CLI** | [`uf`](/docs/reference/cli/) | Project scaffolding, environment setup, health checks, configuration, sandboxed execution, LLM gateway. | | **Agent** | [OpenCode](https://opencode.ai) | The AI coding environment where you interact, write code, and run commands. The personas run inside OpenCode. | | **Planning** | [Speckit](https://github.com/github/spec-kit) (spec-kit) | A specification pipeline that turns ideas into structured specs, plans, and tasks before implementation begins. | | **Coordination** | [Replicator](https://github.com/unbound-force/replicator) | Multi-agent coordination: parallel workers, git-backed tracking, file reservations, and semantic memory. Single Go binary. | diff --git a/content/docs/getting-started/architecture.md b/content/docs/getting-started/architecture.md index 7d32e4e..e801246 100644 --- a/content/docs/getting-started/architecture.md +++ b/content/docs/getting-started/architecture.md @@ -16,7 +16,7 @@ This page presents the six architectural principles that shape how Unbound Force ## Three-Tier Context System -AI agents perform better when given concrete context — real file paths, real code patterns, real project decisions — rather than abstract instructions. Research across multiple AI engineering teams has converged on this finding: showing the agent a map of the territory consistently outperforms giving it a manual of procedures (Yanli Liu, "Harness Engineering," *AI Advances*, Apr 2026). +AI agents perform better when given concrete context — real file paths, real code patterns, real project decisions — rather than abstract instructions. Research across multiple AI engineering teams has converged on this finding: showing the agent a map of the territory consistently outperforms giving it a manual of procedures (Yanli Liu, "Harness Engineering," _AI Advances_, Apr 2026). Unbound Force implements context delivery through three tiers, each serving a different purpose: @@ -48,28 +48,28 @@ Each layer constrains the layers below it. An agent persona cannot override a co ## Control Matrix -How do you classify the different types of controls in an agent system? One useful framework organizes controls along two axes (adapted from ThoughtWorks' agent taxonomy, as described in Liu, "Harness Engineering," *AI Advances*, Apr 2026): +How do you classify the different types of controls in an agent system? One useful framework organizes controls along two axes (adapted from ThoughtWorks' agent taxonomy, as described in Liu, "Harness Engineering," _AI Advances_, Apr 2026): -- **Feedforward vs. feedback**: Does the control guide agents *before* they act (feedforward), or evaluate what they produced *after* (feedback)? +- **Feedforward vs. feedback**: Does the control guide agents _before_ they act (feedforward), or evaluate what they produced _after_ (feedback)? - **Computational vs. inferential**: Is the control deterministic and fast (computational), or does it require judgment and semantic understanding (inferential)? This produces four quadrants: -| | Computational | Inferential | -|---|---|---| -| **Feedforward** (guides before action) | Type systems, linter rules, convention packs, JSON Schema validation | AGENTS.md, constitution, spec artifacts, agent persona instructions, Dewey knowledge retrieval | -| **Feedback** (evaluates after action) | Test suites, [Gaze](/docs/team/gaze-tester/) CRAP scores, coverage analysis, vulnerability scanners | [Divisor Council](/docs/team/the-divisor/) reviews, constitution check, retrospective learnings | +| | Computational | Inferential | +| -------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| **Feedforward** (guides before action) | Type systems, linter rules, convention packs, JSON Schema validation | AGENTS.md, constitution, spec artifacts, agent persona instructions, Dewey knowledge retrieval | +| **Feedback** (evaluates after action) | Test suites, [Gaze](/docs/team/gaze-tester/) CRAP scores, coverage analysis, vulnerability scanners | [Divisor Council](/docs/team/the-divisor/) reviews, constitution check, retrospective learnings | Most teams have strong computational controls (tests, linters) but weak inferential ones (relying on human code review as the only semantic check). Unbound Force invests in all four quadrants — Dewey provides inferential feedforward (semantic context before work begins), and the Divisor Council provides inferential feedback (multi-agent semantic review after work completes). ## Doer/Judge Separation -When the same entity both produces and evaluates work, the evaluation is compromised. An agent that wrote code and then reviews its own code is likely to rationalize its choices rather than find genuine issues. This is a well-documented finding across AI agent research: separating the doer from the judge produces higher-quality output (Anthropic's multi-agent architecture, as described in Liu, "Harness Engineering," *AI Advances*, Apr 2026). +When the same entity both produces and evaluates work, the evaluation is compromised. An agent that wrote code and then reviews its own code is likely to rationalize its choices rather than find genuine issues. This is a well-documented finding across AI agent research: separating the doer from the judge produces higher-quality output (Anthropic's multi-agent architecture, as described in Liu, "Harness Engineering," _AI Advances_, Apr 2026). Unbound Force enforces this separation structurally, not just procedurally: - **[Cobalt-Crush](/docs/team/cobalt-crush/)** writes code. It has full tool access: read, write, edit, bash. -- **[The Divisor](/docs/team/the-divisor/)** reviews code. The Guard agent operates at temperature 0.1 with `write: false`, `edit: false`, `bash: false` — it structurally *cannot* modify files. It can only read and report. +- **[The Divisor](/docs/team/the-divisor/)** reviews code. The Guard agent operates at temperature 0.1 with `write: false`, `edit: false`, `bash: false` — it structurally _cannot_ modify files. It can only read and report. The tool access restriction is the key design choice. A process rule ("don't modify files during review") can be violated. A structural restriction (the agent literally lacks write permissions) cannot. The judge is physically unable to fix what it finds, forcing findings to go through the implementation agent with full visibility. @@ -77,7 +77,7 @@ The Divisor Council extends this further with 5+ specialized review agents runni ## Plan/Execute Separation -Letting an agent plan and execute in the same pass produces unreliable output. Every major AI engineering team has independently discovered this: the planning step must be separate from execution, with its output reviewed before implementation begins (Liu, "Harness Engineering," *AI Advances*, Apr 2026). +Letting an agent plan and execute in the same pass produces unreliable output. Every major AI engineering team has independently discovered this: the planning step must be separate from execution, with its output reviewed before implementation begins (Liu, "Harness Engineering," _AI Advances_, Apr 2026). Unbound Force implements this as an 8-phase pipeline with hard gates between phases: @@ -86,6 +86,7 @@ constitution → specify → clarify → plan → tasks → analyze → checklis ``` The phases enforce a strict progression: + - You cannot plan before you specify - You cannot create tasks before you plan - You cannot implement before spec review passes diff --git a/content/docs/getting-started/artifacts.md b/content/docs/getting-started/artifacts.md index 9711925..f0c00a7 100644 --- a/content/docs/getting-started/artifacts.md +++ b/content/docs/getting-started/artifacts.md @@ -35,15 +35,15 @@ The envelope format ensures that every artifact is machine-parseable (Constituti The swarm defines 7 artifact types. Each has a designated producer hero and one or more consumer heroes: -| Type | Producer | Consumers | Description | -| --------------------- | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ | -| `quality-report` | Gaze | Mx F, Muti-Mind, Cobalt-Crush | Test results, contract coverage data, CRAP scores, and risk analysis from quality validation | +| Type | Producer | Consumers | Description | +| --------------------- | -------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------ | +| `quality-report` | Gaze | Mx F, Muti-Mind, Cobalt-Crush | Test results, contract coverage data, CRAP scores, and risk analysis from quality validation | | `review-verdict` | [The Divisor](/docs/team/the-divisor/) | Mx F, Cobalt-Crush, Muti-Mind | APPROVE or REQUEST CHANGES verdict with per-persona findings from the review council | -| `backlog-item` | Muti-Mind | Mx F, Cobalt-Crush | Feature or bug descriptions with priority scores (5-dimension composite) and acceptance criteria | -| `acceptance-decision` | Muti-Mind | Mx F, Cobalt-Crush | ACCEPT, REJECT, or CONDITIONAL decision with rationale after reviewing the completed increment | -| `metrics-snapshot` | Mx F | Muti-Mind | Velocity, quality trends, review efficiency, and CI health metrics for the current period | -| `coaching-record` | Mx F | All heroes | Learning feedback, actionable recommendations, and convention pack update suggestions | -| `workflow-record` | Swarm Orchestration | Mx F, Muti-Mind | Complete workflow trace with per-stage timings, artifacts produced, and iteration history | +| `backlog-item` | Muti-Mind | Mx F, Cobalt-Crush | Feature or bug descriptions with priority scores (5-dimension composite) and acceptance criteria | +| `acceptance-decision` | Muti-Mind | Mx F, Cobalt-Crush | ACCEPT, REJECT, or CONDITIONAL decision with rationale after reviewing the completed increment | +| `metrics-snapshot` | Mx F | Muti-Mind | Velocity, quality trends, review efficiency, and CI health metrics for the current period | +| `coaching-record` | Mx F | All heroes | Learning feedback, actionable recommendations, and convention pack update suggestions | +| `workflow-record` | Swarm Orchestration | Mx F, Muti-Mind | Complete workflow trace with per-stage timings, artifacts produced, and iteration history | Each artifact type has a registered JSON schema that defines the structure of its `payload` field. Schemas are versioned independently (the `schema_version` envelope field), allowing artifact formats to evolve without breaking consumers. diff --git a/content/docs/getting-started/code-review-tutorial.md b/content/docs/getting-started/code-review-tutorial.md index 927e880..d16c88d 100644 --- a/content/docs/getting-started/code-review-tutorial.md +++ b/content/docs/getting-started/code-review-tutorial.md @@ -41,14 +41,14 @@ The review council runs in two phases: **Phase 2: Divisor Review** — launches 5+ review personas in parallel, each with a different focus: -| Persona | Focus | -|---------|-------| -| **Adversary** | Security, resilience, edge cases | -| **Architect** | Structure, conventions, patterns | -| **Guard** | Intent drift, scope discipline | -| **Testing** | Test coverage, isolation, assertions | -| **SRE** | Deployment, operational readiness | -| **Curator** | Documentation gaps | +| Persona | Focus | +| ------------- | ------------------------------------ | +| **Adversary** | Security, resilience, edge cases | +| **Architect** | Structure, conventions, patterns | +| **Guard** | Intent drift, scope discipline | +| **Testing** | Test coverage, isolation, assertions | +| **SRE** | Deployment, operational readiness | +| **Curator** | Documentation gaps | ### Expected Output @@ -165,15 +165,15 @@ Verdict: 2 findings (1 HIGH, 1 MEDIUM) ## Step 4: Understanding CI Causality -When CI checks fail on your PR, the key question is: *did my changes cause this?* +When CI checks fail on your PR, the key question is: _did my changes cause this?_ `/uf.review-pr` answers this by checking whether the same check also fails on the base branch: -| Base Branch | PR Check | Classification | -|-------------|----------|----------------| -| Pass | Fail | **PR-caused** — your changes introduced this | -| Fail | Fail | **Pre-existing** — failure exists independently | -| No data | Fail | **Unknown** — treated as PR-caused (conservative) | +| Base Branch | PR Check | Classification | +| ----------- | -------- | ------------------------------------------------- | +| Pass | Fail | **PR-caused** — your changes introduced this | +| Fail | Fail | **Pre-existing** — failure exists independently | +| No data | Fail | **Unknown** — treated as PR-caused (conservative) | **PR-caused failures** are reported as HIGH or CRITICAL findings. These are your regressions. @@ -193,6 +193,7 @@ Would you like me to create a fix branch? If you agree, it creates `fix/pr-42-yamllint` from the base branch with a minimal fix. The branch stays local — you review and push when ready. **Safety guards**: + - Will not create a fix branch if you have uncommitted changes (dirty-tree guard) - Will not overwrite an existing branch with the same name (collision check) - Will not attempt non-trivial fixes spanning more than 3 files @@ -219,14 +220,14 @@ You can use either command independently — they do not depend on each other. B ## Decision Table -| Situation | Command | Why | -|-----------|---------|-----| -| Before pushing | `/uf.review-council` | Catch issues locally with 5+ parallel reviewers | -| Post council findings to a PR | `/uf.review-council N` | Multi-persona local review with findings posted as a GitHub PR review | -| After creating a PR | `/uf.review-pr` | Review with CI results and causality analysis | -| Reviewing someone else's PR | `/uf.review-pr 42` | Works on any PR by number | -| CI failed, unsure if my fault | `/uf.review-pr` | Causality classification separates your regressions from noise | -| Want maximum coverage | Both in sequence | `/uf.review-council` pre-push, `/uf.review-pr` post-PR | +| Situation | Command | Why | +| -------------------------------- | ---------------------- | --------------------------------------------------------------------- | +| Before pushing | `/uf.review-council` | Catch issues locally with 5+ parallel reviewers | +| Post council findings to a PR | `/uf.review-council N` | Multi-persona local review with findings posted as a GitHub PR review | +| After creating a PR | `/uf.review-pr` | Review with CI results and causality analysis | +| Reviewing someone else's PR | `/uf.review-pr 42` | Works on any PR by number | +| CI failed, unsure if my fault | `/uf.review-pr` | Causality classification separates your regressions from noise | +| Want maximum coverage | Both in sequence | `/uf.review-council` pre-push, `/uf.review-pr` post-PR | > **`/uf.review-council N` vs `/uf.review-pr N`**: Both target a specific PR, but they serve different purposes. `/uf.review-council N` runs the full multi-persona local review and posts the aggregated findings to the PR. `/uf.review-pr N` fetches CI results, performs causality analysis (PR-caused vs pre-existing failures), and reviews the PR diff with that context. Use `/uf.review-council N` when you want the council's multi-persona review visible on the PR; use `/uf.review-pr N` when you need CI-aware review with causality classification. diff --git a/content/docs/getting-started/config-tutorial.md b/content/docs/getting-started/config-tutorial.md index d8034df..1c82faf 100644 --- a/content/docs/getting-started/config-tutorial.md +++ b/content/docs/getting-started/config-tutorial.md @@ -223,12 +223,12 @@ uf config show --format json ## Summary -| Step | Command | Purpose | -|------|---------|---------| -| Create | `uf config init` | Generate `.uf/config.yaml` with commented defaults | -| Edit | Open `.uf/config.yaml` | Uncomment and change the settings you need | -| Validate | `uf config validate` | Catch typos and invalid values | -| Verify | `uf config show` | See the effective merged configuration | +| Step | Command | Purpose | +| -------- | ---------------------- | -------------------------------------------------- | +| Create | `uf config init` | Generate `.uf/config.yaml` with commented defaults | +| Edit | Open `.uf/config.yaml` | Uncomment and change the settings you need | +| Validate | `uf config validate` | Catch typos and invalid values | +| Verify | `uf config show` | See the effective merged configuration | ## See Also diff --git a/content/docs/getting-started/knowledge.md b/content/docs/getting-started/knowledge.md index dafe8e5..1db1726 100644 --- a/content/docs/getting-started/knowledge.md +++ b/content/docs/getting-started/knowledge.md @@ -76,15 +76,15 @@ export OLLAMA_EMBED_DIM=256 export DEWEY_CHUNK_MAX_CHARS=12288 ``` -| Variable | Default | Description | -| -------- | ------- | ----------- | -| `OLLAMA_MODEL` | `granite-embedding:30m` | Embedding model name passed to Ollama | -| `OLLAMA_EMBED_DIM` | `256` | Embedding vector dimension | -| `DEWEY_CHUNK_MAX_CHARS` | `12288` | Maximum chunk size (in characters) for embedding. Overrides the `embedding.max_chunk_chars` config value when set. | -| `DEWEY_EMBEDDING_ENDPOINT` | — | Overrides the Ollama endpoint for embedding requests. Takes highest precedence (see [Endpoint Resolution](#endpoint-resolution) below). | -| `DEWEY_SYNTHESIS_ENDPOINT` | — | Overrides the Ollama endpoint for synthesis (compilation, curation) requests. Fallback chain: `DEWEY_SYNTHESIS_ENDPOINT` → `OLLAMA_HOST` → `http://localhost:11434`. | -| `DEWEY_AUTHOR` | — | Author tag for learning identities (e.g., `alice`). Used in CI or shared environments to attribute learnings to a specific author. | -| `OLLAMA_HOST` | — | Standard Ollama environment variable. Dewey reads this as a fallback when `DEWEY_EMBEDDING_ENDPOINT` is not set and no `embedding.endpoint` is configured in `config.yaml`. | +| Variable | Default | Description | +| ---------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OLLAMA_MODEL` | `granite-embedding:30m` | Embedding model name passed to Ollama | +| `OLLAMA_EMBED_DIM` | `256` | Embedding vector dimension | +| `DEWEY_CHUNK_MAX_CHARS` | `12288` | Maximum chunk size (in characters) for embedding. Overrides the `embedding.max_chunk_chars` config value when set. | +| `DEWEY_EMBEDDING_ENDPOINT` | — | Overrides the Ollama endpoint for embedding requests. Takes highest precedence (see [Endpoint Resolution](#endpoint-resolution) below). | +| `DEWEY_SYNTHESIS_ENDPOINT` | — | Overrides the Ollama endpoint for synthesis (compilation, curation) requests. Fallback chain: `DEWEY_SYNTHESIS_ENDPOINT` → `OLLAMA_HOST` → `http://localhost:11434`. | +| `DEWEY_AUTHOR` | — | Author tag for learning identities (e.g., `alice`). Used in CI or shared environments to attribute learnings to a specific author. | +| `OLLAMA_HOST` | — | Standard Ollama environment variable. Dewey reads this as a fallback when `DEWEY_EMBEDDING_ENDPOINT` is not set and no `embedding.endpoint` is configured in `config.yaml`. | > **Synthesis vs. embedding precedence**: Synthesis endpoint resolution uses an inverted precedence compared to embedding. For synthesis, `config.yaml` settings take highest priority over environment variables (`config.yaml` > `DEWEY_SYNTHESIS_ENDPOINT` > `OLLAMA_HOST` > default). For embedding, environment variables take highest priority (`DEWEY_EMBEDDING_ENDPOINT` > `config.yaml` > `OLLAMA_HOST` > default). This means setting `DEWEY_SYNTHESIS_ENDPOINT` has no effect if `synthesis.endpoint` is set in `config.yaml`. @@ -663,14 +663,14 @@ Use the `tier` parameter on `dewey_semantic_search_filtered` to filter results b Common issues and how to resolve them: -| Issue | Symptoms | Resolution | -| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| MCP server timeout | OpenCode shows connection timeout | Check `.gitignore` for large directories being indexed; run `dewey reindex` | -| Ollama not running | `dewey doctor` shows embedding layer ✗ | Run `ollama serve` or install Ollama (`brew install --cask ollama`) | +| Issue | Symptoms | Resolution | +| ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| MCP server timeout | OpenCode shows connection timeout | Check `.gitignore` for large directories being indexed; run `dewey reindex` | +| Ollama not running | `dewey doctor` shows embedding layer ✗ | Run `ollama serve` or install Ollama (`brew install --cask ollama`) | | Model not pulled | Semantic search returns no results; log shows "embedding model not available" | Run `ollama pull granite-embedding:30m`. Dewey continues in keyword-only mode until the model is available. | -| Lock file conflicts | "Another dewey instance is running" | Only one `dewey serve` per vault; check for stale `.uf/dewey/.dewey.lock` | -| Low embedding coverage | Semantic search returns few results | Run `dewey index` to generate embeddings for new content | -| Slow startup | First `dewey serve` takes minutes | Normal for large repos on first index; subsequent startups are near-instant. Check `.gitignore` to exclude `node_modules/`, `vendor/`, etc. | +| Lock file conflicts | "Another dewey instance is running" | Only one `dewey serve` per vault; check for stale `.uf/dewey/.dewey.lock` | +| Low embedding coverage | Semantic search returns few results | Run `dewey index` to generate embeddings for new content | +| Slow startup | First `dewey serve` takes minutes | Normal for large repos on first index; subsequent startups are near-instant. Check `.gitignore` to exclude `node_modules/`, `vendor/`, etc. | If `dewey doctor` shows failures, start by addressing the ✗ items — each diagnostic section includes enough context to identify the root cause. diff --git a/content/docs/getting-started/quick-start.md b/content/docs/getting-started/quick-start.md index 1cd7db7..38da91c 100644 --- a/content/docs/getting-started/quick-start.md +++ b/content/docs/getting-started/quick-start.md @@ -71,7 +71,7 @@ Unbound Force runs on four tools that form a layered stack. `uf setup` installs | Layer | Tool | What It Does | | ---------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| **CLI** | [`uf`](/docs/reference/cli/) | Project scaffolding, environment setup, health checks, configuration, sandboxed execution, LLM gateway. | +| **CLI** | [`uf`](/docs/reference/cli/) | Project scaffolding, environment setup, health checks, configuration, sandboxed execution, LLM gateway. | | **Agent** | [OpenCode](https://opencode.ai) | The AI coding environment where you interact, write code, and run commands. The personas run inside OpenCode. | | **Planning** | [Speckit](https://github.com/github/spec-kit) (spec-kit) | A specification pipeline that turns ideas into structured specs, plans, and tasks before implementation begins. | | **Coordination** | [Replicator](https://github.com/unbound-force/replicator) | Multi-agent coordination: parallel workers, git-backed tracking, file reservations, and semantic memory. Single Go binary. | diff --git a/content/docs/getting-started/tester.md b/content/docs/getting-started/tester.md index 18ce682..8c8af74 100644 --- a/content/docs/getting-started/tester.md +++ b/content/docs/getting-started/tester.md @@ -36,7 +36,7 @@ gaze report ./... --ai=opencode # or --ai=claude | Command | What It Produces | | -------------- | ------------------------------------------------------------------------------ | -| `gaze analyze` | Side effect inventory (30+ types across 5 priority tiers) | +| `gaze analyze` | Side effect inventory (dozens of types across 5 priority tiers) | | `gaze quality` | Contract coverage percentage and over-specification score | | `gaze crap` | CRAP score (complexity + coverage risk) and GazeCRAP (using contract coverage) | | `gaze report` | Combined analysis formatted as a human-readable markdown report via AI | @@ -123,6 +123,8 @@ Coverage ratchets prevent test quality from degrading over time. Once a coverage The recommended CI pattern uses `--coverprofile` to pass a pre-generated Go coverage profile to Gaze. This eliminates the double-test-run — tests run once for coverage, and Gaze reuses the profile instead of running `go test` internally. +> **Migration note**: Gaze no longer passes `-short` to `go test` during internal coverage runs. Coverage now reflects the full test suite by default, which may change CRAP scores after upgrade. Add `--test-short` to restore the previous behavior. See the [Gaze migration notes](/docs/projects/gaze/#migration-notes) for details. + ```bash # 1. Run tests with coverage profile go test -race -count=1 -coverprofile=coverage.out ./... @@ -132,11 +134,13 @@ gaze report ./... --ai=opencode \ --coverprofile=coverage.out \ --max-crapload=50 \ --min-contract-coverage=50 + # Optional: add --test-short if Gaze runs its own coverage + # and you want to skip expensive integration tests # 3. Gaze auto-appends to GitHub Actions step summary ``` -The `--coverprofile` flag accepts a path to a Go coverage profile generated by `go test -coverprofile`. When provided, Gaze skips its internal test run and uses the existing profile directly. +The `--coverprofile` flag accepts a path to a Go coverage profile generated by `go test -coverprofile`. When provided, Gaze skips its internal test run and uses the existing profile directly. The `--test-short` flag is only relevant when Gaze runs its own internal `go test` — if you pass `--coverprofile`, the flag has no effect since Gaze does not run tests. ### How Ratchets Work diff --git a/content/docs/projects/_index.md b/content/docs/projects/_index.md index 74d86cf..f54fc40 100644 --- a/content/docs/projects/_index.md +++ b/content/docs/projects/_index.md @@ -12,7 +12,7 @@ toc: false ### [Gaze](/docs/projects/gaze/) -Test quality analysis via side effect detection for Go. Gaze detects every observable side effect a function produces, classifies each effect as contractual or incidental, and measures whether your tests actually assert on the things that matter. It introduces three metrics -- Contract Coverage, Over-Specification Score, and GazeCRAP -- that go beyond line coverage to reveal the real quality of your test suite. +Test quality analysis via side effect detection — Go-native, with multi-language support via external analyzers. Gaze detects every observable side effect a function produces, classifies each effect as contractual or incidental, and measures whether your tests actually assert on the things that matter. It introduces three metrics -- Contract Coverage, Over-Specification Score, and GazeCRAP -- that go beyond line coverage to reveal the real quality of your test suite. ### [Dewey](/docs/projects/dewey/) diff --git a/content/docs/projects/gaze.md b/content/docs/projects/gaze.md index 75d6338..3861632 100644 --- a/content/docs/projects/gaze.md +++ b/content/docs/projects/gaze.md @@ -1,7 +1,7 @@ --- title: "Gaze" -description: "Test quality analysis via side effect detection for Go — Contract Coverage, Over-Specification Score, and GazeCRAP metrics that go beyond line coverage." -lead: "Test quality analysis via side effect detection for Go." +description: "Test quality analysis via side effect detection — Contract Coverage, Over-Specification, and GazeCRAP. Go-native with multi-language support." +lead: "Test quality analysis via side effect detection — Go-native, with multi-language support via external analyzers." date: 2026-02-23T00:00:00+00:00 draft: false weight: 20 @@ -20,7 +20,7 @@ Gaze fixes this by working from first principles: 2. **Classify** each effect as _contractual_ (part of the function's public obligation), _incidental_ (an implementation detail), or _ambiguous_. 3. **Measure** whether your tests actually assert on the contractual effects — and flag the ones they do not. -Gaze requires no annotations, no test framework changes, and no restructuring of your code. It analyzes your existing Go packages as-is. +For Go projects, Gaze requires no annotations, no test framework changes, and no restructuring of your code. It analyzes your existing packages as-is. Other languages are supported through [external analyzers](#external-analyzers). ## Key Metrics @@ -134,15 +134,30 @@ Both `--ai=opencode` and `--ai=claude` are fully supported AI backends for `gaze ### CLI Flags -| Flag | Commands | Description | -| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--include-unexported` | `analyze`, `quality` | Include unexported functions in the analysis. Auto-detected per-package for `package main` (see note below). | -| `--ai-mapper` | `quality`, `crap` | Enable AI-assisted assertion mapping as a 5th pass (confidence 50). Uses the configured AI adapter to evaluate structurally disconnected assertions. | -| `--max-gaze-crapload` | `report` | Fail if more than N functions exceed the GazeCRAP threshold. Similar to `--max-crapload` but uses contract coverage instead of line coverage. | -| `--coverprofile` | `report` | Pass a pre-generated `go test -coverprofile` to skip Gaze's internal test run. See the [Tester guide](/docs/getting-started/tester/) for the CI pattern. | +| Flag | Commands | Description | +| ---------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--include-unexported` | `analyze`, `quality` | Include unexported functions in the analysis. Auto-detected per-package for `package main` (see note below). | +| `--ai-mapper` | `quality`, `crap` | Enable AI-assisted assertion mapping as a 5th pass (confidence 50). Uses the configured AI adapter to evaluate structurally disconnected assertions. | +| `--max-gaze-crapload` | `report` | Fail if more than N functions exceed the GazeCRAP threshold. Similar to `--max-crapload` but uses contract coverage instead of line coverage. | +| `--coverprofile` | `report` | Pass a pre-generated `go test -coverprofile` to skip Gaze's internal test run. See the [Tester guide](/docs/getting-started/tester/) for the CI pattern. | +| `--analyzer ` | `crap`, `quality`, `report` | Specify an external analyzer binary implementing the JSON-RPC 2.0 protocol. See [External Analyzers](#external-analyzers). | +| `--language ` | `crap`, `quality`, `report` | Specify the target language when using an external analyzer (e.g., `python`, `javascript`). | +| `--test-short` | `crap`, `report`, `self-check` | Pass `-short` to `go test` during Gaze's internal coverage run. By default, Gaze now runs the full test suite. | **`--include-unexported` auto-detection**: When analyzing multiple packages, each package is checked individually for `package main`. CLI entry points are included automatically without needing this flag. +### External Analyzers + +Gaze supports languages beyond Go through the external analyzer protocol. Any tool that implements the [JSON-RPC 2.0 analyzer protocol](https://github.com/unbound-force/gaze/blob/main/docs/protocol.md) can provide side effect data to Gaze, enabling the same Contract Coverage and CRAP metrics for non-Go codebases. + +Gaze discovers external analyzers through a three-tier mechanism: + +1. **CLI flag** — `--analyzer ` on `gaze crap`, `gaze quality`, or `gaze report` +2. **Configuration** — the `analyzers` section in `.gaze.yaml` maps language names to analyzer binaries +3. **PATH convention** — binaries named `gaze-analyzer-` (e.g., `gaze-analyzer-python`) are discovered automatically + +Use the `--language ` flag to specify the target language when running with an external analyzer. Gaze also supports a streaming mode for large codebases; see [the protocol documentation](https://github.com/unbound-force/gaze/blob/main/docs/protocol.md) for details. + ### The `/gaze fix` Command The `/gaze fix` command provides AI-assisted test generation to close coverage gaps. It reads quality data — contract coverage gaps and fix strategy labels — and generates Go test functions using the `gaze-test-generator` agent. @@ -209,9 +224,25 @@ Gaze is structured as a set of focused packages: | `docscan` | Documentation file scanner for enhanced classification | | `aireport` | AI CLI adapter integration for `gaze report` AI pipeline | | `scaffold` | OpenCode file scaffolding for `/gaze` command setup | +| `protocol` | JSON-RPC 2.0 external analyzer protocol implementation | +| `provider` | Analyzer provider abstraction and discovery logic | +| `adapter` | Language-specific adapter wiring for external analyzers | +| `cliutil` | Shared CLI utilities and flag handling | The analysis engine detects side effects across three implemented tiers (P0, P1, P2), covering the most common and impactful effect types — from return values and error returns through mutations, I/O, channel operations, and more. +### Universal Side Effect Types + +With the external analyzer protocol, Gaze's taxonomy has expanded to dozens of types including 10 universal types that apply across languages: + +- **P0**: `ErrorSignal` — language-agnostic error signaling (exceptions, error returns, panics) +- **P1**: `GeneratorYield`, `ContainerMutation`, `StreamOutput` — iterator/generator effects, collection mutations, stream writes +- **P2**: `AsyncGeneratorYield`, `MetaprogrammingMutation`, `DescriptorEffect`, `ResourceManagement`, `ImportSideEffect`, `MonkeyPatch` — async generators, metaprogramming, descriptors, resource lifecycle, import effects, runtime patching + +Each side effect can carry a `Detail` metadata field (`map[string]any`) for language-specific context that external analyzers can populate. + +For the complete type reference, see the [protocol documentation](https://github.com/unbound-force/gaze/blob/main/docs/protocol.md). + ### Analysis Engine Details These details are primarily relevant for understanding Gaze's output and accuracy characteristics: @@ -228,11 +259,32 @@ These details are primarily relevant for understanding Gaze's output and accurac Gaze is actively developed. The current scope has known boundaries: - **Direct function body only.** Gaze analyzes the immediate function body. Transitive side effects (effects produced by called functions) are out of scope for v1. -- **P3-P4 side effects not yet detected.** P0 through P2 are fully implemented — covering return values, error returns, mutations, I/O, channel operations, file system operations, database writes, goroutine spawns, panics, and context cancellation. P3-P4 side effects (stdout/stderr, environment mutations, mutex operations, reflection, unsafe) are not yet detected. +- **P3-P4 side effects not yet detected (Go analysis).** P0 through P2 are fully implemented — covering return values, error returns, mutations, I/O, channel operations, file system operations, database writes, goroutine spawns, panics, and context cancellation. P3-P4 side effects (stdout/stderr, environment mutations, mutex operations, reflection, unsafe) are not yet detected in Go analysis. External analyzers define their own detection scope. - **Assertion mapping accuracy is ~84.7%** (83/98 mapped assertions, ratchet floor 84.0%). The target is 90%. Accuracy is primarily limited by helper function assertions and testify field-access patterns (tracked as [GitHub Issue #6](https://github.com/unbound-force/gaze/issues/6)). - **No CGo or unsafe analysis.** Functions using `cgo` or `unsafe.Pointer` are not analyzed for their specific side effects. - **No transitive multi-module analysis.** All four commands (`analyze`, `quality`, `crap`, `report`) accept multiple package patterns including `./...` wildcards, but analysis is scoped to the current module. Cross-module dependency analysis is out of scope for v1. +## Migration Notes + +If you are upgrading to Gaze v1.7.0, the following breaking changes may affect your workflow. + +### JSON Output Changes + +- The `go_version` field in all JSON output has been renamed to `language_version`. Update any scripts or CI pipelines that parse this field. +- A new `language` field has been added to JSON output (e.g., `"language": "go"`). +- Language-neutral `SideEffectType` aliases have been added (e.g., `AsyncTaskSpawn`, `AsyncMessageSend`, `BarrierOp`, `PanicRecovery`, `FFICall`). These are equivalent to existing Go-specific types but use language-agnostic names. See the [protocol documentation](https://github.com/unbound-force/gaze/blob/main/docs/protocol.md) for the full list. + +### Protocol Version Bump + +- The external analyzer protocol version has been bumped to **v1.1.0**. Existing analyzers implementing v1.0.0 remain compatible; the bump reflects new optional fields (`language`, `Detail` metadata) that v1.0.0 analyzers can safely ignore. + +### Coverage Behavior Change + +- Gaze no longer passes `-short` to `go test` during internal coverage runs. Coverage now reflects the full test suite by default. +- Use `--test-short` to restore the previous behavior if your test suite has expensive integration tests you want to skip during coverage collection. +- The `GAZE_COVERAGE_RUN=1` environment variable is set during Gaze's internal test runs, allowing tests to detect when they are running under Gaze coverage. +- **CRAP scores may change after upgrade.** Because coverage now includes the full test suite, functions that were previously measured with `-short` coverage will have different coverage numbers — and therefore different CRAP and GazeCRAP scores. + ## Learn More - [GitHub Repository](https://github.com/unbound-force/gaze) — source code, issues, and releases diff --git a/content/docs/reference/cli.md b/content/docs/reference/cli.md index 76ccd33..cefc731 100644 --- a/content/docs/reference/cli.md +++ b/content/docs/reference/cli.md @@ -20,9 +20,9 @@ The `uf` CLI (alias for `unbound-force`) manages the full Unbound Force toolchai **Global flags:** -| Flag | Description | -|------|-------------| -| `-h`, `--help` | Help for any command | +| Flag | Description | +| ----------------- | -------------------- | +| `-h`, `--help` | Help for any command | | `-v`, `--version` | Print the uf version | ## init @@ -35,12 +35,12 @@ User-owned files (templates, scripts, agents, config) are skipped if they alread uf init [flags] ``` -| Flag | Description | -|------|-------------| -| `--divisor` | Deploy only Divisor review agents and convention packs | -| `--force` | Overwrite all existing files and re-index Dewey workspace (with `--no-embeddings` — embedding generation is deferred) | -| `--lang ` | Project language for convention pack selection: `go`, `python`, or `typescript` (auto-detected from `go.mod`, `pyproject.toml`, `setup.py`, `package.json`, etc. if omitted) | -| `--platform ` | Target AI coding platform: `opencode` (default) or `cursor`. Repeatable for dual-platform scaffolding (e.g., `--platform opencode --platform cursor`) | +| Flag | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--divisor` | Deploy only Divisor review agents and convention packs | +| `--force` | Overwrite all existing files and re-index Dewey workspace (with `--no-embeddings` — embedding generation is deferred) | +| `--lang ` | Project language for convention pack selection: `go`, `python`, or `typescript` (auto-detected from `go.mod`, `pyproject.toml`, `setup.py`, `package.json`, etc. if omitted) | +| `--platform ` | Target AI coding platform: `opencode` (default) or `cursor`. Repeatable for dual-platform scaffolding (e.g., `--platform opencode --platform cursor`) | If any sub-tool fails during initialization, `uf init` displays the actual error output from the failing command so you can diagnose the issue directly. @@ -54,11 +54,11 @@ Install and configure the Unbound Force development toolchain. Detects existing uf setup [flags] ``` -| Flag | Description | -|------|-------------| -| `--dir ` | Target directory for setup (default `.`) | -| `--dry-run` | Print actions without executing | -| `--yes` | Skip confirmation prompts (does **not** auto-confirm third-party curl installers — see below) | +| Flag | Description | +| ---------------- | --------------------------------------------------------------------------------------------- | +| `--dir ` | Target directory for setup (default `.`) | +| `--dry-run` | Print actions without executing | +| `--yes` | Skip confirmation prompts (does **not** auto-confirm third-party curl installers — see below) | ### Install cascade @@ -110,9 +110,9 @@ Exit code 0 when all checks pass or only warnings exist. Exit code 1 when any ch uf doctor [flags] ``` -| Flag | Description | -|------|-------------| -| `--dir ` | Target directory to check (default `.`) | +| Flag | Description | +| ------------------- | ------------------------------------------------ | +| `--dir ` | Target directory to check (default `.`) | | `--format ` | Output format: `text` or `json` (default `text`) | ### Platform-aware install hints @@ -143,11 +143,11 @@ uf config [command] [flags] ### Subcommands -| Subcommand | Description | -|------------|-------------| -| `init` | Create or update `.uf/config.yaml` | -| `show` | Display effective configuration after all layers merge | -| `validate` | Validate config file against known field values | +| Subcommand | Description | +| ---------- | ------------------------------------------------------ | +| `init` | Create or update `.uf/config.yaml` | +| `show` | Display effective configuration after all layers merge | +| `validate` | Validate config file against known field values | ### config init @@ -155,8 +155,8 @@ uf config [command] [flags] uf config init [flags] ``` -| Flag | Description | -|------|-------------| +| Flag | Description | +| ---------------- | ------------------------------ | | `--dir ` | Target directory (default `.`) | ### config show @@ -165,9 +165,9 @@ uf config init [flags] uf config show [flags] ``` -| Flag | Description | -|------|-------------| -| `--dir ` | Target directory (default `.`) | +| Flag | Description | +| ------------------- | ------------------------------------------------ | +| `--dir ` | Target directory (default `.`) | | `--format ` | Output format: `text` or `json` (default `text`) | ### config validate @@ -176,9 +176,9 @@ uf config show [flags] uf config validate [flags] ``` -| Flag | Description | -|------|-------------| -| `--dir ` | Target directory (default `.`) | +| Flag | Description | +| ------------------- | ------------------------------------------------ | +| `--dir ` | Target directory (default `.`) | | `--format ` | Output format: `text` or `json` (default `text`) | ## sandbox @@ -191,15 +191,15 @@ uf sandbox [command] [flags] ### Subcommands -| Subcommand | Description | -|------------|-------------| -| `create` | Provision a persistent sandbox workspace | -| `start` | Launch or resume a sandbox | -| `stop` | Stop a sandbox (preserves persistent state) | -| `attach` | Connect to a running sandbox's TUI | -| `extract` | Extract changes from the sandbox as git patches | -| `status` | Show sandbox workspace status | -| `destroy` | Permanently delete a sandbox workspace | +| Subcommand | Description | +| ---------- | ----------------------------------------------- | +| `create` | Provision a persistent sandbox workspace | +| `start` | Launch or resume a sandbox | +| `stop` | Stop a sandbox (preserves persistent state) | +| `attach` | Connect to a running sandbox's TUI | +| `extract` | Extract changes from the sandbox as git patches | +| `status` | Show sandbox workspace status | +| `destroy` | Permanently delete a sandbox workspace | Key flags available on sandbox subcommands: @@ -224,18 +224,18 @@ Start a local reverse proxy that serves the Anthropic Messages API. The gateway uf gateway [flags] ``` -| Flag | Description | -|------|-------------| -| `--detach` | Run gateway in the background | -| `--port ` | Port to listen on (default `53147`) | +| Flag | Description | +| --------------------- | --------------------------------------------------------------------------------- | +| `--detach` | Run gateway in the background | +| `--port ` | Port to listen on (default `53147`) | | `--provider ` | Provider override: `anthropic`, `vertex`, or `bedrock` (auto-detected if omitted) | ### Subcommands -| Subcommand | Description | -|------------|-------------| -| `status` | Show gateway status | -| `stop` | Stop a running gateway | +| Subcommand | Description | +| ---------- | ---------------------- | +| `status` | Show gateway status | +| `stop` | Stop a running gateway | ## ollama-proxy diff --git a/content/docs/reference/config.md b/content/docs/reference/config.md index a532971..b26eea5 100644 --- a/content/docs/reference/config.md +++ b/content/docs/reference/config.md @@ -23,8 +23,8 @@ uf config init # current directory uf config init --dir ./myproject ``` -| Flag | Description | -|------|-------------| +| Flag | Description | +| ---------------- | ------------------------------ | | `--dir ` | Target directory (default `.`) | ### config show @@ -36,9 +36,9 @@ uf config show # human-readable text uf config show --format json # machine-parseable JSON ``` -| Flag | Description | -|------|-------------| -| `--dir ` | Target directory (default `.`) | +| Flag | Description | +| ------------------- | ------------------------------------------------ | +| `--dir ` | Target directory (default `.`) | | `--format ` | Output format: `text` or `json` (default `text`) | ### config validate @@ -50,9 +50,9 @@ uf config validate uf config validate --format json ``` -| Flag | Description | -|------|-------------| -| `--dir ` | Target directory (default `.`) | +| Flag | Description | +| ------------------- | ------------------------------------------------ | +| `--dir ` | Target directory (default `.`) | | `--format ` | Output format: `text` or `json` (default `text`) | ## Layered Loading @@ -75,17 +75,17 @@ Missing config files are not an error. If neither file exists, compiled defaults Every config field can be overridden with an environment variable. The naming convention is `UF_` + section + `_` + field in uppercase: -| Environment Variable | Config Field | -|---------------------|--------------| +| Environment Variable | Config Field | +| -------------------------- | ----------------------- | | `UF_SETUP_PACKAGE_MANAGER` | `setup.package_manager` | -| `UF_SCAFFOLD_LANGUAGE` | `scaffold.language` | -| `UF_EMBEDDING_MODEL` | `embedding.model` | -| `UF_EMBEDDING_DIMENSIONS` | `embedding.dimensions` | -| `UF_SANDBOX_RUNTIME` | `sandbox.runtime` | -| `UF_SANDBOX_IMAGE` | `sandbox.image` | -| `UF_SANDBOX_IDE` | `sandbox.ide` | -| `UF_GATEWAY_PORT` | `gateway.port` | -| `UF_GATEWAY_PROVIDER` | `gateway.provider` | +| `UF_SCAFFOLD_LANGUAGE` | `scaffold.language` | +| `UF_EMBEDDING_MODEL` | `embedding.model` | +| `UF_EMBEDDING_DIMENSIONS` | `embedding.dimensions` | +| `UF_SANDBOX_RUNTIME` | `sandbox.runtime` | +| `UF_SANDBOX_IMAGE` | `sandbox.image` | +| `UF_SANDBOX_IDE` | `sandbox.ide` | +| `UF_GATEWAY_PORT` | `gateway.port` | +| `UF_GATEWAY_PROVIDER` | `gateway.provider` | ### Precedence Example @@ -95,15 +95,15 @@ If your user config sets `gateway.port: 8080` and your repo config sets `gateway The config file has 7 sections. Each controls a specific part of the `uf` toolchain: -| Section | Purpose | Key Settings | -|---------|---------|-------------| -| **setup** | Controls how `uf setup` installs tools | `package_manager` (auto, brew, dnf, apt), `skip` (tools to skip) | -| **scaffold** | Controls what `uf init` deploys | `language` (auto-detected from go.mod, pyproject.toml, package.json, etc.) | -| **embedding** | Embedding model for Dewey semantic search | `model` (default: granite-embedding:30m), `dimensions` (default: 256) | -| **sandbox** | Controls `uf sandbox` containerized sessions | `runtime` (auto, podman, docker), `image`, `ide` (none, vscode, cursor, etc.), `resources.memory` | -| **gateway** | Controls `uf gateway` LLM reverse proxy | `port` (default: 53147), `provider` (auto, anthropic, vertex, bedrock) | -| **doctor** | Controls `uf doctor` health checks | `skip` (checks to skip), `tools` (custom tool paths) | -| **workflow** | Controls hero lifecycle execution modes | `execution_modes.define` (human/swarm), `spec_review` (true/false) | +| Section | Purpose | Key Settings | +| ------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| **setup** | Controls how `uf setup` installs tools | `package_manager` (auto, brew, dnf, apt), `skip` (tools to skip) | +| **scaffold** | Controls what `uf init` deploys | `language` (auto-detected from go.mod, pyproject.toml, package.json, etc.) | +| **embedding** | Embedding model for Dewey semantic search | `model` (default: granite-embedding:30m), `dimensions` (default: 256) | +| **sandbox** | Controls `uf sandbox` containerized sessions | `runtime` (auto, podman, docker), `image`, `ide` (none, vscode, cursor, etc.), `resources.memory` | +| **gateway** | Controls `uf gateway` LLM reverse proxy | `port` (default: 53147), `provider` (auto, anthropic, vertex, bedrock) | +| **doctor** | Controls `uf doctor` health checks | `skip` (checks to skip), `tools` (custom tool paths) | +| **workflow** | Controls hero lifecycle execution modes | `execution_modes.define` (human/swarm), `spec_review` (true/false) | ## Common Customizations diff --git a/content/docs/reference/gateway.md b/content/docs/reference/gateway.md index 20e1d8a..93ddb63 100644 --- a/content/docs/reference/gateway.md +++ b/content/docs/reference/gateway.md @@ -27,10 +27,10 @@ uf gateway --port 9090 # custom port uf gateway --provider vertex # override auto-detection ``` -| Flag | Description | -|------|-------------| -| `--detach` | Run in the background as a daemon | -| `--port ` | Port to listen on (default `53147`) | +| Flag | Description | +| --------------------- | --------------------------------------------------------------------------------- | +| `--detach` | Run in the background as a daemon | +| `--port ` | Port to listen on (default `53147`) | | `--provider ` | Provider override: `anthropic`, `vertex`, or `bedrock` (auto-detected if omitted) | ### gateway status @@ -53,11 +53,11 @@ uf gateway stop The gateway scans environment variables to detect your cloud provider. The first match wins: -| Priority | Provider | Detection Condition | -|----------|----------|-------------------| -| 1 | **Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1` + `ANTHROPIC_VERTEX_PROJECT_ID` set | -| 2 | **Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | -| 3 | **Anthropic** | `ANTHROPIC_API_KEY` set | +| Priority | Provider | Detection Condition | +| -------- | ------------- | -------------------------------------------------------------- | +| 1 | **Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1` + `ANTHROPIC_VERTEX_PROJECT_ID` set | +| 2 | **Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | +| 3 | **Anthropic** | `ANTHROPIC_API_KEY` set | Vertex AI is checked first because a developer may have both `ANTHROPIC_API_KEY` and Vertex env vars set — the more specific provider wins. diff --git a/content/docs/reference/sandbox.md b/content/docs/reference/sandbox.md index 4c2ff10..870ce06 100644 --- a/content/docs/reference/sandbox.md +++ b/content/docs/reference/sandbox.md @@ -34,18 +34,18 @@ uf sandbox start --detach # start without attaching uf sandbox start --image my-image # custom container image ``` -| Flag | Description | -|------|-------------| -| `--mode ` | Mount mode: `isolated` (read-only, default) or `direct` (read-write) | -| `--detach` | Start container without attaching the TUI | -| `--image ` | Container image (default from `UF_SANDBOX_IMAGE` or `quay.io/unbound-force/opencode-dev:latest`) | -| `--memory ` | Container memory limit (default `8g`) | -| `--cpus ` | Container CPU limit (default `4`) | -| `--backend ` | Backend: `auto`, `podman`, or `che` (default `auto`) | -| `--ide ` | IDE for DevPod to open after start: `none` (default), `vscode`, `openvscode`, `fleet`, `jupyternotebook`, `cursor` | -| `--uidmap` | Use explicit UID/GID mapping (macOS escape hatch) | +| Flag | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `--mode ` | Mount mode: `isolated` (read-only, default) or `direct` (read-write) | +| `--detach` | Start container without attaching the TUI | +| `--image ` | Container image (default from `UF_SANDBOX_IMAGE` or `quay.io/unbound-force/opencode-dev:latest`) | +| `--memory ` | Container memory limit (default `8g`) | +| `--cpus ` | Container CPU limit (default `4`) | +| `--backend ` | Backend: `auto`, `podman`, or `che` (default `auto`) | +| `--ide ` | IDE for DevPod to open after start: `none` (default), `vscode`, `openvscode`, `fleet`, `jupyternotebook`, `cursor` | +| `--uidmap` | Use explicit UID/GID mapping (macOS escape hatch) | | `--provider ` | DevPod provider name (default `podman`). References a registered DevPod provider — does not require the binary in PATH. Registered automatically by `uf setup` | -| `--no-parent` | Mount only the project directory (disable parent directory mount) | +| `--no-parent` | Mount only the project directory (disable parent directory mount) | ### sandbox stop @@ -72,8 +72,8 @@ uf sandbox extract # interactive confirmation uf sandbox extract --yes # skip confirmation ``` -| Flag | Description | -|------|-------------| +| Flag | Description | +| ------- | ---------------------------- | | `--yes` | Skip the confirmation prompt | ### sandbox status @@ -163,18 +163,18 @@ uf sandbox create --name my-project-sandbox # custom name uf sandbox create --demo-ports 3000,8080 # expose demo ports ``` -| Flag | Description | -|------|-------------| -| `--name ` | Workspace name override (default `uf-sandbox-`) | -| `--backend ` | Backend: `auto`, `podman`, or `che` (default `auto`) | -| `--demo-ports ` | Additional ports to expose for demos (comma-separated) | -| `--image ` | Container image (Podman only) | -| `--memory ` | Memory limit (default `8g`) | -| `--cpus ` | CPU limit (default `4`) | -| `--detach` | Start without attaching the TUI | -| `--ide ` | IDE for DevPod to open after creation: `none` (default), `vscode`, `openvscode`, `fleet`, `jupyternotebook`, `cursor` | +| Flag | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `--name ` | Workspace name override (default `uf-sandbox-`) | +| `--backend ` | Backend: `auto`, `podman`, or `che` (default `auto`) | +| `--demo-ports ` | Additional ports to expose for demos (comma-separated) | +| `--image ` | Container image (Podman only) | +| `--memory ` | Memory limit (default `8g`) | +| `--cpus ` | CPU limit (default `4`) | +| `--detach` | Start without attaching the TUI | +| `--ide ` | IDE for DevPod to open after creation: `none` (default), `vscode`, `openvscode`, `fleet`, `jupyternotebook`, `cursor` | | `--provider ` | DevPod provider name (default `podman`). References a registered DevPod provider — does not require the binary in PATH. Registered automatically by `uf setup` | -| `--uidmap` | Use explicit UID/GID mapping | +| `--uidmap` | Use explicit UID/GID mapping | ### sandbox destroy @@ -186,9 +186,9 @@ uf sandbox destroy --yes # skip confirmation uf sandbox destroy --force # destroy even if running ``` -| Flag | Description | -|------|-------------| -| `--yes` | Skip the confirmation prompt | +| Flag | Description | +| --------- | ---------------------------------------------- | +| `--yes` | Skip the confirmation prompt | | `--force` | Force destroy even if the workspace is running | ### Workspace Detection @@ -223,12 +223,12 @@ uf sandbox create --backend podman # force Podman/DevPod backend (default) Backend resolution follows a priority chain: -| Priority | Source | Example | -|----------|--------|---------| -| 1 | CLI flag | `--backend podman` | -| 2 | Environment variable | `UF_SANDBOX_BACKEND=podman` | -| 3 | Config file | `sandbox.backend: podman` in `.uf/config.yaml` | -| 4 | Auto-detect | Podman (default) | +| Priority | Source | Example | +| -------- | -------------------- | ------------------------------------------------- | +| 1 | CLI flag | `--backend podman` | +| 2 | Environment variable | `UF_SANDBOX_BACKEND=podman` | +| 3 | Config file | `sandbox.backend: podman` in `.uf/config.yaml` | +| 4 | Auto-detect | Podman (default) | ### Eclipse Che / Dev Spaces (Legacy — Deprecated) @@ -244,12 +244,12 @@ If you encounter a migration error when using `--backend che`, switch to the def The `--ide` flag controls which IDE DevPod opens after workspace creation or start. The value is resolved through a priority chain: -| Priority | Source | Example | -|----------|--------|---------| -| 1 | CLI flag | `--ide vscode` | -| 2 | Environment variable | `UF_SANDBOX_IDE=cursor` | -| 3 | Config file | `sandbox.ide: vscode` in `.uf/config.yaml` | -| 4 | Default | `none` (no IDE opened) | +| Priority | Source | Example | +| -------- | -------------------- | ------------------------------------------ | +| 1 | CLI flag | `--ide vscode` | +| 2 | Environment variable | `UF_SANDBOX_IDE=cursor` | +| 3 | Config file | `sandbox.ide: vscode` in `.uf/config.yaml` | +| 4 | Default | `none` (no IDE opened) | Valid values: `none`, `vscode`, `openvscode`, `fleet`, `jupyternotebook`, `cursor`. @@ -259,14 +259,14 @@ When set to a value other than `none`, DevPod opens the specified IDE and connec The sandbox provides several isolation layers: -| Property | Description | -|----------|-------------| -| **Rootless Podman** | Container runs without root privileges on the host | -| **Read-only mounts** | Isolated mode mounts the project read-only (default) | -| **No push credentials** | Git push credentials are never forwarded to the container | -| **Resource limits** | Memory (default 8g) and CPU (default 4) limits prevent runaway processes | -| **SELinux** | Auto-detects SELinux and applies `:Z` volume labels on enforcing systems | -| **Non-root user** | Container runs as UID 1000 (non-root) inside the namespace | +| Property | Description | +| ----------------------- | ------------------------------------------------------------------------ | +| **Rootless Podman** | Container runs without root privileges on the host | +| **Read-only mounts** | Isolated mode mounts the project read-only (default) | +| **No push credentials** | Git push credentials are never forwarded to the container | +| **Resource limits** | Memory (default 8g) and CPU (default 4) limits prevent runaway processes | +| **SELinux** | Auto-detects SELinux and applies `:Z` volume labels on enforcing systems | +| **Non-root user** | Container runs as UID 1000 (non-root) inside the namespace | ### API Key Forwarding diff --git a/content/docs/team/dewey.md b/content/docs/team/dewey.md index 46d53ef..b3ad409 100644 --- a/content/docs/team/dewey.md +++ b/content/docs/team/dewey.md @@ -133,7 +133,7 @@ To configure the default Ollama provider, edit `.uf/dewey/config.yaml`: embedding: provider: ollama model: granite-embedding:30m - max_chunk_chars: 12288 # Maximum chunk size for embedding (default: 12288) + max_chunk_chars: 12288 # Maximum chunk size for embedding (default: 12288) # Alternative: granite-embedding:278m for multilingual content ``` diff --git a/content/docs/team/gaze-tester.md b/content/docs/team/gaze-tester.md index f8e98e5..aa6dd04 100644 --- a/content/docs/team/gaze-tester.md +++ b/content/docs/team/gaze-tester.md @@ -1,8 +1,8 @@ --- title: "Gaze" slug: "gaze-tester" -description: "Gaze is the Tester of the Unbound Force swarm — a quality analysis tool for Go that measures test quality through side effect detection and contract coverage." -lead: "The Quality Sentinel — Test Quality Analysis for Go" +description: "Gaze is the Tester — a quality analysis tool measuring test quality via side effect detection and contract coverage. Go-native with multi-language support." +lead: "The Quality Sentinel — Test Quality Analysis" date: 2026-02-23T00:00:00+00:00 draft: false weight: 40 @@ -13,13 +13,13 @@ toc: true ## The Quality Sentinel -Gaze is the Tester of the Unbound Force swarm -- a static analysis tool for Go that answers a question line coverage cannot: are your tests actually verifying the behavior that matters? +Gaze is the Tester of the Unbound Force swarm -- a static analysis tool that answers a question line coverage cannot: are your tests actually verifying the behavior that matters? Go-native, Gaze also supports other languages through the [external analyzer protocol](/docs/projects/gaze/#external-analyzers). Traditional coverage metrics tell you what code executed during tests. Gaze goes further by detecting the **observable side effects** of each function (return values, state mutations, I/O operations) and checking whether your tests actually assert on those effects. The result is **contract coverage** -- a measure of what was verified, not just what ran. ## What Gaze Does Today -Gaze provides three core capabilities for Go codebases: +Gaze provides three core capabilities — Go-native, with multi-language support via external analyzers: - **Contract Coverage** -- Measures the percentage of a function's observable side effects that are verified by assertions in tests. A function that writes to a database but whose tests never check the database state has low contract coverage even with 100% line coverage. - **GazeCRAP Scores** -- Combines cyclomatic complexity with contract coverage (not line coverage) to identify functions that are both complex and poorly verified. High GazeCRAP scores indicate the riskiest code in your project. diff --git a/layouts/_partials/footer/script-footer-custom.html b/layouts/_partials/footer/script-footer-custom.html index 87ec0d6..e96900c 100644 --- a/layouts/_partials/footer/script-footer-custom.html +++ b/layouts/_partials/footer/script-footer-custom.html @@ -1 +1,2 @@ -{{/* Required by @thulite/doks-core _partials/footer/script-footer.html — do not remove. */}} +{{/* Required by @thulite/doks-core _partials/footer/script-footer.html — do not +remove. */}} diff --git a/layouts/home.html b/layouts/home.html index 472564d..ea9dc44 100644 --- a/layouts/home.html +++ b/layouts/home.html @@ -102,8 +102,8 @@

Unleash

3

Finale

- Ship it. Commit, push, create a PR, watch CI, and return to - main — all in one command. + Ship it. Commit, push, create a PR, watch CI, and return to main — + all in one command.

Projects
GoGo + Multi-Language CLI Tool
diff --git a/openspec/changes/architecture-page/design.md b/openspec/changes/architecture-page/design.md index 306d6fb..d61ccca 100644 --- a/openspec/changes/architecture-page/design.md +++ b/openspec/changes/architecture-page/design.md @@ -7,6 +7,7 @@ The proposal (proposal.md) established constitution alignment: Content Accuracy ## Goals / Non-Goals ### Goals + - Present the unified system architecture in a single page that connects existing concepts - Cover the six key architectural concepts: three-tier context, layered governance, control matrix, doer/judge separation, plan/execute separation, composability - Frame content for a website audience ("why should I care") rather than raw technical detail @@ -14,6 +15,7 @@ The proposal (proposal.md) established constitution alignment: Content Accuracy - Cross-reference existing pages (constitution, developer, knowledge, common-workflows, team pages) where those pages contain deeper detail ### Non-Goals + - Rebranding around "harness engineering" -- the superhero team identity remains primary - Reproducing the full harness engineering analysis -- this is a website page, not an internal document - Adding custom HTML, diagrams, or interactive elements -- pure Markdown only diff --git a/openspec/changes/architecture-page/proposal.md b/openspec/changes/architecture-page/proposal.md index d91288f..5a62f58 100644 --- a/openspec/changes/architecture-page/proposal.md +++ b/openspec/changes/architecture-page/proposal.md @@ -13,12 +13,15 @@ GitHub Issue: #88 ## Capabilities ### New Capabilities + - `architecture-page`: A documentation page that presents the overall system architecture including the three-tier context system, layered governance model, control matrix, doer/judge separation, plan/execute separation, and composability ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/architecture-page/specs/architecture-page.md b/openspec/changes/architecture-page/specs/architecture-page.md index f19625d..ce08183 100644 --- a/openspec/changes/architecture-page/specs/architecture-page.md +++ b/openspec/changes/architecture-page/specs/architecture-page.md @@ -5,6 +5,7 @@ The website MUST include a documentation page at `content/docs/getting-started/architecture.md` that presents the overall system architecture and design philosophy of Unbound Force. The page MUST cover the following architectural concepts: + 1. Three-tier context system (static docs, versioned rules, dynamic semantic memory) 2. Layered governance model (constitution > convention packs > agent personas > commands > CI) 3. Control matrix (feedforward/feedback x computational/inferential) diff --git a/openspec/changes/blog-8-phase-pipeline/design.md b/openspec/changes/blog-8-phase-pipeline/design.md index 288bc56..ed78dd8 100644 --- a/openspec/changes/blog-8-phase-pipeline/design.md +++ b/openspec/changes/blog-8-phase-pipeline/design.md @@ -5,12 +5,14 @@ The unleash-in-practice post covers the pipeline mechanics. Issue #97 calls for ## Goals / Non-Goals ### Goals + - Explain why two-phase plan/execute is insufficient for complex features - Walk through each of the 8 phases and why each gate exists - Cover the enforcement mechanisms (filesystem markers, branch naming, spec commit gate, CI parity gate) - Show how the pipeline enforces incrementalism at the specification level ### Non-Goals + - Duplicating the step-by-step operational guide from unleash-in-practice - Adding custom HTML or styling - Modifying existing pages diff --git a/openspec/changes/blog-8-phase-pipeline/proposal.md b/openspec/changes/blog-8-phase-pipeline/proposal.md index d811518..f5d5a29 100644 --- a/openspec/changes/blog-8-phase-pipeline/proposal.md +++ b/openspec/changes/blog-8-phase-pipeline/proposal.md @@ -11,12 +11,15 @@ GitHub Issue: #97 ## Capabilities ### New Capabilities + - `blog-8-phase-pipeline`: Blog post explaining why plan/execute separation extends to 8 phases with hard gates ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-build-to-delete/design.md b/openspec/changes/blog-build-to-delete/design.md index ef44457..8a9d99d 100644 --- a/openspec/changes/blog-build-to-delete/design.md +++ b/openspec/changes/blog-build-to-delete/design.md @@ -5,12 +5,14 @@ Liu's article includes a "build to delete" section about harness decay. The anal ## Goals / Non-Goals ### Goals + - Explain the harness decay concept with concrete examples - Classify Unbound Force components into decay-resistant and decay-prone categories - Provide a practical pruning methodology - Be honest about the system's weight ### Non-Goals + - Modifying existing pages or components - Making predictions about specific model versions - Custom HTML or styling diff --git a/openspec/changes/blog-build-to-delete/proposal.md b/openspec/changes/blog-build-to-delete/proposal.md index 710a756..7f7c3dc 100644 --- a/openspec/changes/blog-build-to-delete/proposal.md +++ b/openspec/changes/blog-build-to-delete/proposal.md @@ -11,12 +11,15 @@ GitHub Issue: #92 ## Capabilities ### New Capabilities + - `blog-build-to-delete`: Blog post on harness decay and the discipline of pruning agent system components ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-convention-packs/design.md b/openspec/changes/blog-convention-packs/design.md index 02d3e08..8d9cb42 100644 --- a/openspec/changes/blog-convention-packs/design.md +++ b/openspec/changes/blog-convention-packs/design.md @@ -5,12 +5,14 @@ Convention packs are versioned rule sets deployed via `uf init`. They use number ## Goals / Non-Goals ### Goals + - Explain the problem (prose standards in AGENTS.md that drift across projects) - Show pack structure with real examples from go.md - Cover the -custom.md extension pattern - Connect to the ThoughtWorks "harness templates" concept ### Non-Goals + - Full pack reference documentation (that's for a dedicated docs page) - Modifying existing pages diff --git a/openspec/changes/blog-convention-packs/proposal.md b/openspec/changes/blog-convention-packs/proposal.md index 06222c6..fc200cb 100644 --- a/openspec/changes/blog-convention-packs/proposal.md +++ b/openspec/changes/blog-convention-packs/proposal.md @@ -11,12 +11,15 @@ GitHub Issue: #93 ## Capabilities ### New Capabilities + - `blog-convention-packs`: Blog post on convention packs as reusable harness templates ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-doer-judge/design.md b/openspec/changes/blog-doer-judge/design.md index 2c67bcf..43abf8b 100644 --- a/openspec/changes/blog-doer-judge/design.md +++ b/openspec/changes/blog-doer-judge/design.md @@ -5,12 +5,14 @@ The Divisor Council enforces doer/judge separation structurally — the Guard ag ## Goals / Non-Goals ### Goals + - Explain why structural enforcement (tool access restrictions) is superior to behavioral instructions - Describe the layered feedback stack (CI → Gaze → Divisor agents) - Cover the 3-iteration review cap as a pragmatic constraint - Attribute Anthropic findings to Liu article ### Non-Goals + - Detailed Divisor agent persona documentation (that belongs in team pages) - Modifying existing pages - Adding diagrams or custom HTML diff --git a/openspec/changes/blog-doer-judge/proposal.md b/openspec/changes/blog-doer-judge/proposal.md index 5068901..a86a0fd 100644 --- a/openspec/changes/blog-doer-judge/proposal.md +++ b/openspec/changes/blog-doer-judge/proposal.md @@ -13,12 +13,15 @@ GitHub Issue: #91 ## Capabilities ### New Capabilities + - `blog-doer-judge`: Blog post on structural doer/judge separation in AI code review ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-five-principles/design.md b/openspec/changes/blog-five-principles/design.md index 53fc293..01ff8bf 100644 --- a/openspec/changes/blog-five-principles/design.md +++ b/openspec/changes/blog-five-principles/design.md @@ -7,6 +7,7 @@ The proposal (proposal.md) established constitution alignment: Content Accuracy ## Goals / Non-Goals ### Goals + - Present each of Liu's five convergence principles with concrete Unbound Force evidence - Show how the principles reinforce each other (not independent) - Be honest about harness weight and the "build to delete" concern @@ -15,6 +16,7 @@ The proposal (proposal.md) established constitution alignment: Content Accuracy - Link to getting-started guide as CTA ### Non-Goals + - Reproducing the full harness engineering analysis document - Adding diagrams or custom HTML elements - Modifying existing blog posts or pages diff --git a/openspec/changes/blog-five-principles/proposal.md b/openspec/changes/blog-five-principles/proposal.md index 52d623c..e0d8402 100644 --- a/openspec/changes/blog-five-principles/proposal.md +++ b/openspec/changes/blog-five-principles/proposal.md @@ -13,12 +13,15 @@ GitHub Issue: #89 ## Capabilities ### New Capabilities + - `blog-five-principles`: A blog post presenting Unbound Force's system architecture through the lens of five convergence principles discovered independently by OpenAI, Anthropic, and ThoughtWorks ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-five-principles/specs/blog-five-principles.md b/openspec/changes/blog-five-principles/specs/blog-five-principles.md index ed76954..cafe1ad 100644 --- a/openspec/changes/blog-five-principles/specs/blog-five-principles.md +++ b/openspec/changes/blog-five-principles/specs/blog-five-principles.md @@ -5,6 +5,7 @@ The website MUST include a blog post at `content/blog/five-principles-every-ai-agent-harness-discovers.md` that presents Unbound Force's system architecture through the lens of five convergence principles. The post MUST cover all five principles: + 1. Context beats instructions (three-tier context system) 2. Planning and execution must be separated (8-phase pipeline) 3. Feedback loops are non-negotiable (layered CI → Gaze → Divisor) diff --git a/openspec/changes/blog-gateway-credentials/design.md b/openspec/changes/blog-gateway-credentials/design.md index 7760570..f55a9e2 100644 --- a/openspec/changes/blog-gateway-credentials/design.md +++ b/openspec/changes/blog-gateway-credentials/design.md @@ -5,6 +5,7 @@ The website has a gateway reference page (PR #77) covering the command surface. ## Goals / Non-Goals ### Goals + - Write a blog post following the BA-001 narrative arc (problem → approach → evidence → CTA) - Lead with "your container sees localhost, not Google Cloud" per BA-007 - Include a concrete before/after comparison (6 env vars → 2) @@ -12,6 +13,7 @@ The website has a gateway reference page (PR #77) covering the command surface. - Cover token refresh as a key reliability feature ### Non-Goals + - Duplicate the reference docs (command flags, full Vertex translation details) — link to them instead - Deep SigV4 signing implementation details (internal concern) - Performance benchmarks or latency analysis @@ -34,6 +36,7 @@ The website has a gateway reference page (PR #77) covering the command surface. ## Content Sources Authoritative upstream sources: + - Gateway implementation: `unbound-force/unbound-force/internal/gateway/` (provider.go, refresh.go, gateway.go, sse.go) - CLI help: `uf gateway --help` - Specs: `unbound-force/unbound-force/specs/033-gateway-command/`, `unbound-force/unbound-force/specs/034-gateway-vertex-translation/` diff --git a/openspec/changes/blog-gateway-credentials/proposal.md b/openspec/changes/blog-gateway-credentials/proposal.md index 751c62a..355359c 100644 --- a/openspec/changes/blog-gateway-credentials/proposal.md +++ b/openspec/changes/blog-gateway-credentials/proposal.md @@ -20,12 +20,15 @@ A new blog post at `content/blog/gateway-credentials.md` with the narrative arc: ## Capabilities ### New Capabilities + - `blog/gateway-credentials`: Blog post covering gateway credential isolation design ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-gateway-credentials/tasks.md b/openspec/changes/blog-gateway-credentials/tasks.md index 684808c..b63b3e8 100644 --- a/openspec/changes/blog-gateway-credentials/tasks.md +++ b/openspec/changes/blog-gateway-credentials/tasks.md @@ -28,5 +28,5 @@ - [x] 5.4 Verify all internal links resolve (no dead links) - [ ] 5.5 Run `npm run dev` and verify the post renders correctly - [ ] 5.6 Verify both light and dark mode rendering - - + + diff --git a/openspec/changes/blog-sandbox-isolation/design.md b/openspec/changes/blog-sandbox-isolation/design.md index cd3e9ea..3761755 100644 --- a/openspec/changes/blog-sandbox-isolation/design.md +++ b/openspec/changes/blog-sandbox-isolation/design.md @@ -5,6 +5,7 @@ The website has 7 blog posts covering Gaze, Dewey, /unleash, and the Curator. No ## Goals / Non-Goals ### Goals + - Write a blog post following the BA-001 narrative arc (problem → approach → evidence → CTA) - Include a step-by-step walkthrough of the round-trip: start → work → extract → verify - Lead with benefit framing per BA-007 ("your repo is untouchable" not "we added a sandbox") @@ -12,6 +13,7 @@ The website has 7 blog posts covering Gaze, Dewey, /unleash, and the Curator. No - Be honest about current limitations per VB-004 ### Non-Goals + - Duplicate the reference docs (commands, flags, UID mapping details) — link to them instead - Cover CDE/Che backend (experimental, not ready for a public blog post) - Cover persistent workspaces in depth (the walkthrough uses ephemeral sessions) @@ -34,6 +36,7 @@ The website has 7 blog posts covering Gaze, Dewey, /unleash, and the Curator. No ## Content Sources Authoritative upstream sources for walkthrough content: + - CLI help: `uf sandbox --help`, `uf sandbox start --help`, `uf sandbox extract --help` - Sandbox implementation: `unbound-force/unbound-force/internal/sandbox/` - Manual test script: `unbound-force/unbound-force/temp/uf-sandbox-manual-test.md` (22 test scenarios) diff --git a/openspec/changes/blog-sandbox-isolation/proposal.md b/openspec/changes/blog-sandbox-isolation/proposal.md index ea1596f..418794c 100644 --- a/openspec/changes/blog-sandbox-isolation/proposal.md +++ b/openspec/changes/blog-sandbox-isolation/proposal.md @@ -1,6 +1,6 @@ ## Why -The `uf sandbox` command shipped in v0.12.0 with 7 subcommands, two mount modes, UID mapping, and persistent workspaces. The reference documentation (PR #79) covers the command surface, but there is no narrative content explaining *why* containerized agent sessions matter. Engineers evaluating Unbound Force need a concrete walkthrough showing the round-trip workflow: start a sandbox, work inside it, extract changes back to the host. The security benefits (read-only mounts, no credential forwarding, resource limits) are significant but not self-evident from a reference page. +The `uf sandbox` command shipped in v0.12.0 with 7 subcommands, two mount modes, UID mapping, and persistent workspaces. The reference documentation (PR #79) covers the command surface, but there is no narrative content explaining _why_ containerized agent sessions matter. Engineers evaluating Unbound Force need a concrete walkthrough showing the round-trip workflow: start a sandbox, work inside it, extract changes back to the host. The security benefits (read-only mounts, no credential forwarding, resource limits) are significant but not self-evident from a reference page. This change addresses [GitHub issue #40](https://github.com/unbound-force/website/issues/40). @@ -19,12 +19,15 @@ The blog post follows the content pack narrative arc (BA-001: problem → approa ## Capabilities ### New Capabilities + - `blog/sandbox-isolation`: Blog post covering sandbox motivation, walkthrough, and security model ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/blog-sandbox-isolation/tasks.md b/openspec/changes/blog-sandbox-isolation/tasks.md index 725f3e7..009ab86 100644 --- a/openspec/changes/blog-sandbox-isolation/tasks.md +++ b/openspec/changes/blog-sandbox-isolation/tasks.md @@ -31,5 +31,5 @@ - [x] 5.4 Verify all internal links resolve (no dead links) - [x] 5.5 Run `npm run dev` and verify the post renders correctly - [x] 5.6 Verify both light and dark mode rendering - - + + diff --git a/openspec/changes/cli-reference-and-positioning/design.md b/openspec/changes/cli-reference-and-positioning/design.md index e19d0d5..4907e21 100644 --- a/openspec/changes/cli-reference-and-positioning/design.md +++ b/openspec/changes/cli-reference-and-positioning/design.md @@ -5,12 +5,14 @@ The `uf` CLI is the primary user interface for Unbound Force — it installs, co ## Goals / Non-Goals ### Goals + - Create a comprehensive CLI reference page listing all commands, subcommands, and flags - Add `uf` as a layer in the stack positioning table - Create a changelog page for tracking release-level changes - Establish a reference section in the docs navigation ### Non-Goals + - Detailed tutorials for each command (covered by separate tutorial specs) - Exhaustive flag documentation for `sandbox` and `gateway` (covered by their own doc specs) - Backfilling changelog entries for historical releases (include the current release only) diff --git a/openspec/changes/cli-reference-and-positioning/proposal.md b/openspec/changes/cli-reference-and-positioning/proposal.md index 747100d..bf41e78 100644 --- a/openspec/changes/cli-reference-and-positioning/proposal.md +++ b/openspec/changes/cli-reference-and-positioning/proposal.md @@ -17,16 +17,19 @@ This change addresses GitHub issues #62 (CLI reference page) and #68 (changelog ## Capabilities ### New Capabilities + - `docs/reference/cli`: Complete CLI reference page with all command groups and subcommands - `docs/changelog/`: Release changelog page tracking user-facing changes per version ### Modified Capabilities + - `docs/getting-started/_index.md`: Stack table and heading updated to include `uf` CLI layer (4 layers) - `docs/getting-started/quick-start`: Stack table and prose updated to include `uf` CLI layer - `docs/getting-started/common-workflows.md`: Clarifying note added to Code Review persona table - `config/_default/menus/menus.en.toml`: Navigation updated for new reference and changelog sections ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/cli-reference-and-positioning/specs/cli-reference.md b/openspec/changes/cli-reference-and-positioning/specs/cli-reference.md index 0a5a8b1..4f4d1d7 100644 --- a/openspec/changes/cli-reference-and-positioning/specs/cli-reference.md +++ b/openspec/changes/cli-reference-and-positioning/specs/cli-reference.md @@ -5,6 +5,7 @@ The website MUST have a CLI reference page at `content/docs/reference/cli.md` that lists all current `uf` command groups and subcommands, sourced from `uf --help` output at implementation time. Each command group MUST include: + - Command name and brief description - Table of subcommands (if applicable) with flags and descriptions - Link to detailed documentation page (if one exists) @@ -24,6 +25,7 @@ The page MUST include a version marker indicating which `uf` version the referen The website MUST have a changelog page at `content/docs/changelog/_index.md` tracking user-facing changes for the current release. Each release entry MUST include: + - Version number and date - Summary of user-facing changes grouped by type (Added, Changed, Fixed) @@ -57,12 +59,12 @@ Previously: The stack table listed 3 layers (Agent: OpenCode, Planning: Speckit, The updated table MUST show 4 layers: -| Layer | Tool | What It Does | -|-------|------|-------------| -| CLI | `uf` | Project scaffolding, environment setup, health checks, configuration, sandboxed execution, LLM gateway | -| Agent | OpenCode | AI coding environment | -| Planning | Speckit | Specification pipeline | -| Coordination | Replicator | Multi-agent coordination | +| Layer | Tool | What It Does | +| ------------ | ---------- | ------------------------------------------------------------------------------------------------------ | +| CLI | `uf` | Project scaffolding, environment setup, health checks, configuration, sandboxed execution, LLM gateway | +| Agent | OpenCode | AI coding environment | +| Planning | Speckit | Specification pipeline | +| Coordination | Replicator | Multi-agent coordination | #### Scenario: user reads stack table on getting-started pages diff --git a/openspec/changes/cli-reference-and-positioning/tasks.md b/openspec/changes/cli-reference-and-positioning/tasks.md index 3ddb16f..e589a68 100644 --- a/openspec/changes/cli-reference-and-positioning/tasks.md +++ b/openspec/changes/cli-reference-and-positioning/tasks.md @@ -25,5 +25,5 @@ - [ ] 5.3 Run `npm run dev` and verify: CLI reference page renders with all command groups and version marker, changelog page renders with current release, stack table shows 4 layers on getting-started index and quick-start, Reference and Changelog sections appear in navigation - [x] 5.4 Verify all internal links in new pages resolve to existing pages (no dead links) - [ ] 5.5 Verify both light and dark mode rendering for new pages - - + + diff --git a/openspec/changes/config-docs/design.md b/openspec/changes/config-docs/design.md index 0de88e7..b027760 100644 --- a/openspec/changes/config-docs/design.md +++ b/openspec/changes/config-docs/design.md @@ -5,6 +5,7 @@ The `uf config` command group was added via the `opsx/unified-config` change. It ## Goals / Non-Goals ### Goals + - Document all 3 subcommands (`init`, `show`, `validate`) with usage examples - Explain the layered loading system with precedence rules - Describe the 7 configuration sections with key settings @@ -12,6 +13,7 @@ The `uf config` command group was added via the `opsx/unified-config` change. It - Update `common-workflows.md` to reference `uf config` commands ### Non-Goals + - Exhaustive documentation of every config key (the generated template from `uf config init` serves this purpose) - Tutorial-style walkthrough (tracked in GitHub issue #67: Configuration Tutorial) - Config migration guide from old `.uf/sandbox.yaml` format @@ -34,6 +36,7 @@ The `uf config` command group was added via the `opsx/unified-config` change. It ## Content Sources Authoritative upstream source files for documentation content: + - Config struct and loading: `unbound-force/unbound-force/internal/config/config.go` - Config init template: `unbound-force/unbound-force/internal/config/template.go` - Config validation: `unbound-force/unbound-force/internal/config/validate.go` diff --git a/openspec/changes/config-docs/proposal.md b/openspec/changes/config-docs/proposal.md index d68c104..db767af 100644 --- a/openspec/changes/config-docs/proposal.md +++ b/openspec/changes/config-docs/proposal.md @@ -18,12 +18,15 @@ A new documentation page for the `uf config` command covering: ## Capabilities ### New Capabilities + - `docs/reference/config`: Comprehensive configuration documentation page ### Modified Capabilities + - `docs/getting-started/common-workflows`: Updated to reference `uf config` commands alongside existing `.uf/config.yaml` mentions ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/config-docs/tasks.md b/openspec/changes/config-docs/tasks.md index fb7ec72..0b91b0a 100644 --- a/openspec/changes/config-docs/tasks.md +++ b/openspec/changes/config-docs/tasks.md @@ -33,5 +33,5 @@ - [x] 6.3 Verify page appears in Reference section navigation - [ ] 6.4 Verify both light and dark mode rendering - [x] 6.5 Verify all internal links resolve (no dead links) - - + + diff --git a/openspec/changes/critical-doc-fixes/design.md b/openspec/changes/critical-doc-fixes/design.md index eda10ab..d7692f7 100644 --- a/openspec/changes/critical-doc-fixes/design.md +++ b/openspec/changes/critical-doc-fixes/design.md @@ -5,11 +5,13 @@ The website has four factual errors or stale data points in its getting-started ## Goals / Non-Goals ### Goals + - Correct all four factual errors in a single change - Ensure corrected text matches the shipped command behavior (source of truth: `.opencode/command/*.md` in the `unbound-force` repo) - Preserve page structure, frontmatter, and surrounding content ### Non-Goals + - Restructuring the getting-started section - Adding new documentation pages - Updating command reference tables (covered by separate CLI reference change) diff --git a/openspec/changes/critical-doc-fixes/proposal.md b/openspec/changes/critical-doc-fixes/proposal.md index c2f8950..2e21607 100644 --- a/openspec/changes/critical-doc-fixes/proposal.md +++ b/openspec/changes/critical-doc-fixes/proposal.md @@ -19,9 +19,11 @@ Four surgical text corrections across four documentation pages: ## Capabilities ### New Capabilities + - None ### Modified Capabilities + - `docs/getting-started/common-workflows`: Corrected `/finale` and `/unleash` descriptions - `docs/getting-started/quick-start`: Corrected `/finale` description (both code blocks) - `docs/getting-started/developer`: Corrected `/finale` description (4 locations), file count, and command breakdown @@ -29,6 +31,7 @@ Four surgical text corrections across four documentation pages: - `blog/unleash-in-practice`: Corrected `/finale` description in "The Complete Loop" section ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/critical-doc-fixes/tasks.md b/openspec/changes/critical-doc-fixes/tasks.md index a9be967..7a44e31 100644 --- a/openspec/changes/critical-doc-fixes/tasks.md +++ b/openspec/changes/critical-doc-fixes/tasks.md @@ -23,5 +23,5 @@ - [x] 5.1 Run `npm run build` and confirm no build errors - [ ] 5.2 Run `npm run dev` and visually verify all corrected pages render correctly - [x] 5.3 Search all files under `content/` for remaining references to `/finale` merging PRs or `/unleash` rejecting `opsx/*` branches (colloquial uses of "ship" that don't imply PR merging are acceptable) - - + + diff --git a/openspec/changes/cross-references/design.md b/openspec/changes/cross-references/design.md index fe35f51..ec586bf 100644 --- a/openspec/changes/cross-references/design.md +++ b/openspec/changes/cross-references/design.md @@ -5,10 +5,12 @@ Seven cross-reference links missing between existing pages. Issue #96 specifies ## Goals / Non-Goals ### Goals + - Add all 7 cross-reference links specified in the issue - Keep additions minimal and contextually appropriate ### Non-Goals + - Restructuring any page - Adding links to pages from other unmerged branches diff --git a/openspec/changes/cross-references/proposal.md b/openspec/changes/cross-references/proposal.md index 46f24fe..077b694 100644 --- a/openspec/changes/cross-references/proposal.md +++ b/openspec/changes/cross-references/proposal.md @@ -12,12 +12,15 @@ GitHub Issue: #96 ## Capabilities ### New Capabilities + - None ### Modified Capabilities -- Enhanced navigation between constitution.md, the-divisor.md, developer.md, common-workflows.md, contributing/_index.md, artifacts.md, and quick-start.md + +- Enhanced navigation between constitution.md, the-divisor.md, developer.md, common-workflows.md, contributing/\_index.md, artifacts.md, and quick-start.md ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/cross-references/tasks.md b/openspec/changes/cross-references/tasks.md index b952ddd..62daa36 100644 --- a/openspec/changes/cross-references/tasks.md +++ b/openspec/changes/cross-references/tasks.md @@ -4,7 +4,7 @@ - [x] 1.2 the-divisor.md → tester.md (Gaze): link in "Gaze's green light" context - [x] 1.3 developer.md (gatekeeping) → the-divisor.md (Guard, Adversary): link personas that enforce - [x] 1.4 common-workflows.md (code review) → the-divisor.md (ownership): link to ownership table -- [x] 1.5 contributing/_index.md → developer.md (convention packs): standards contributors face +- [x] 1.5 contributing/\_index.md → developer.md (convention packs): standards contributors face - [x] 1.6 artifacts.md → the-divisor.md (review-verdict): link artifact type to producer - [x] 1.7 quick-start.md → constitution.md: mention constitution prerequisite diff --git a/openspec/changes/dewey-embedding-model-docs/design.md b/openspec/changes/dewey-embedding-model-docs/design.md index 886a214..1f7fd54 100644 --- a/openspec/changes/dewey-embedding-model-docs/design.md +++ b/openspec/changes/dewey-embedding-model-docs/design.md @@ -11,6 +11,7 @@ The default embedding model remains `granite-embedding:30m` -- the R2 model is n ## Goals / Non-Goals ### Goals + - Document `DEWEY_CHUNK_MAX_CHARS` env var with its default value (12288) and purpose - Document `embedding.max_chunk_chars` config field in the YAML config example - Document the `dewey doctor` legacy model advisory @@ -18,6 +19,7 @@ The default embedding model remains `granite-embedding:30m` -- the R2 model is n - Keep all existing content accurate -- additive changes only ### Non-Goals + - Changing the default model in installation commands (R2 is not yet on Ollama) - Adding new pages or sections -- all changes fit within existing page structures - Updating `ollama pull` commands (will be a follow-up when R2 is published) diff --git a/openspec/changes/dewey-embedding-model-docs/proposal.md b/openspec/changes/dewey-embedding-model-docs/proposal.md index 2355428..e974ea6 100644 --- a/openspec/changes/dewey-embedding-model-docs/proposal.md +++ b/openspec/changes/dewey-embedding-model-docs/proposal.md @@ -16,15 +16,18 @@ Update three Dewey documentation pages to reflect the embedding model upgrade: ## Capabilities ### New Capabilities + - `DEWEY_CHUNK_MAX_CHARS documentation`: Environment variable reference for the new chunk size override - `max_chunk_chars config documentation`: Configuration field reference for embedding chunk size limits - `Legacy model advisory documentation`: Explanation of the `dewey doctor` informational note about Granite Embedding R2 ### Modified Capabilities + - `Embedding Model section`: Updated to mention chunk size configurability and the R2 upgrade path - `Doctor section`: Updated to include the legacy model advisory diagnostic ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/dewey-embedding-model-docs/specs/embedding-model-docs.md b/openspec/changes/dewey-embedding-model-docs/specs/embedding-model-docs.md index 21cd8e2..20f5b2b 100644 --- a/openspec/changes/dewey-embedding-model-docs/specs/embedding-model-docs.md +++ b/openspec/changes/dewey-embedding-model-docs/specs/embedding-model-docs.md @@ -5,6 +5,7 @@ The getting started guide (`content/docs/getting-started/knowledge.md`) MUST document the `DEWEY_CHUNK_MAX_CHARS` environment variable in the Embedding Model Alignment section. The documentation MUST include the variable name, default value (12288), and a description stating it overrides the configured max chunk characters for embedding. #### Scenario: User looks up DEWEY_CHUNK_MAX_CHARS in docs + - **GIVEN** a user has encountered the `DEWEY_CHUNK_MAX_CHARS` env var in Dewey's source or help output - **WHEN** they navigate to the Knowledge Retrieval getting started guide - **THEN** they find `DEWEY_CHUNK_MAX_CHARS` documented in the Embedding Model Alignment section with its default value and purpose @@ -14,6 +15,7 @@ The getting started guide (`content/docs/getting-started/knowledge.md`) MUST doc The team page (`content/docs/team/dewey.md`) MUST add `max_chunk_chars` to the existing `embedding:` YAML config example in the Embedding Model section. The field SHOULD include a comment explaining its purpose and default value. #### Scenario: User configures embedding chunk size via config + - **GIVEN** a user wants to customize the embedding chunk size - **WHEN** they read the Embedding Model section on the Dewey team page - **THEN** they find `max_chunk_chars` in the YAML example with a comment indicating the default (12288) and its effect @@ -23,6 +25,7 @@ The team page (`content/docs/team/dewey.md`) MUST add `max_chunk_chars` to the e The getting started guide (`content/docs/getting-started/knowledge.md`) MUST document the `dewey doctor` legacy model advisory in the Diagnostic and Maintenance Commands section. The documentation MUST explain that an informational note appears when `granite-embedding:30m` is configured, suggesting an upgrade to the Granite Embedding R2 model when it becomes available. #### Scenario: User sees legacy model advisory in dewey doctor output + - **GIVEN** a user runs `dewey doctor` and sees an informational advisory about the legacy embedding model - **WHEN** they check the website documentation for explanation - **THEN** they find a description of the advisory in the `dewey doctor` section explaining it is informational and that R2 is a future upgrade @@ -32,6 +35,7 @@ The getting started guide (`content/docs/getting-started/knowledge.md`) MUST doc The project page (`content/docs/projects/dewey.md`) and team page (`content/docs/team/dewey.md`) SHOULD mention the Granite Embedding R2 model as a future upgrade path in their respective Embedding Model or Semantic Search sections. The language MUST NOT present R2 as currently available or as an action item -- it SHOULD use forward-looking language indicating a future default change. #### Scenario: User reads about Dewey's embedding model + - **GIVEN** a user is reading about Dewey's embedding model on the project or team page - **WHEN** they review the embedding model details - **THEN** they see a note indicating that a future release will update the default to Granite Embedding R2 @@ -43,6 +47,7 @@ The project page (`content/docs/projects/dewey.md`) and team page (`content/docs The existing `embedding:` YAML config example in `content/docs/team/dewey.md` (lines 129-133) MUST be extended to include the `max_chunk_chars` field. Previously, the example only showed `provider`, `model`, and a comment about alternatives. #### Scenario: Config example includes chunk size + - **GIVEN** a user reads the Embedding Model section on the team page - **WHEN** they view the YAML config example - **THEN** the example includes `max_chunk_chars: 12288` with an explanatory comment, in addition to the existing `provider` and `model` fields @@ -52,6 +57,7 @@ The existing `embedding:` YAML config example in `content/docs/team/dewey.md` (l The existing `dewey doctor` diagnostic table in `content/docs/getting-started/knowledge.md` (lines 380-388) MUST be updated to reflect that the Embedding Layer section now also checks for legacy model advisories. Previously, the Embedding Layer row only mentioned Ollama availability and model status. #### Scenario: Doctor table reflects legacy model check + - **GIVEN** a user reviews the `dewey doctor` diagnostic table in the getting started guide - **WHEN** they look at the Embedding Layer row - **THEN** the description mentions legacy model advisory detection alongside Ollama availability and model status diff --git a/openspec/changes/dewey-embedding-model-docs/tasks.md b/openspec/changes/dewey-embedding-model-docs/tasks.md index 908d2fe..6c29847 100644 --- a/openspec/changes/dewey-embedding-model-docs/tasks.md +++ b/openspec/changes/dewey-embedding-model-docs/tasks.md @@ -35,5 +35,5 @@ - [x] 4.2 Run `npm run dev` and visually verify the three updated pages render correctly with all new content visible and properly formatted. - [x] 4.3 Verify consistency across all three pages -- ensure env var names, default values, and R2 language are identical wherever they appear. - - + + diff --git a/openspec/changes/fix-specify-init-docs/design.md b/openspec/changes/fix-specify-init-docs/design.md index b6eda2d..2eae4e5 100644 --- a/openspec/changes/fix-specify-init-docs/design.md +++ b/openspec/changes/fix-specify-init-docs/design.md @@ -7,12 +7,14 @@ This change updates 3 Markdown files to add specify initialization as a document ## Goals / Non-Goals ### Goals + - Document that `uf init` performs specify initialization as a sub-tool step - Describe the behavioral model: offline (no network calls), directory-scoped (`.specify/` created in current directory), OpenCode-targeted - Maintain consistent abstraction level across all three affected pages - Frame the change from the user's perspective, not as internal implementation detail ### Non-Goals + - Documenting `specify init` as a standalone user-facing command (users run `uf init`, not `specify init`) - Adding troubleshooting content for `.specify/` creation failures (out of scope unless a natural fit exists in the existing structure) - Creating new pages or sections — all changes fit within existing content structure diff --git a/openspec/changes/fix-specify-init-docs/proposal.md b/openspec/changes/fix-specify-init-docs/proposal.md index ef09d73..cf54a35 100644 --- a/openspec/changes/fix-specify-init-docs/proposal.md +++ b/openspec/changes/fix-specify-init-docs/proposal.md @@ -13,25 +13,28 @@ Currently, the Sub-Tool Initialization section (`developer.md`, lines 317-327) d ## What Changes ### New Capabilities + - None — no new website features ### Modified Capabilities + - `developer.md Sub-Tool Initialization`: Add specify initialization as a documented sub-tool step, describing the behavioral model (offline, directory-scoped, OpenCode-targeted) - `cli.md init section`: Add a note that `uf init` also initializes the Speckit specification framework via specify - `common-workflows.md setup flow`: Update the sub-tool initialization summary to include specify initialization ### Removed Capabilities + - None ## Impact **Files affected** (content changes only — no templates, SCSS, or configuration): -| File | Section | Change | -|------|---------|--------| -| `content/docs/getting-started/developer.md` | Sub-Tool Initialization (lines 317-327) | Add specify initialization bullet describing offline, directory-scoped behavior | -| `content/docs/reference/cli.md` | init section (lines 28-43) | Add mention that init also runs specify initialization | -| `content/docs/getting-started/common-workflows.md` | Setup flow (line 436) | Update sub-tool initialization summary to include specify | +| File | Section | Change | +| -------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- | +| `content/docs/getting-started/developer.md` | Sub-Tool Initialization (lines 317-327) | Add specify initialization bullet describing offline, directory-scoped behavior | +| `content/docs/reference/cli.md` | init section (lines 28-43) | Add mention that init also runs specify initialization | +| `content/docs/getting-started/common-workflows.md` | Setup flow (line 436) | Update sub-tool initialization summary to include specify | **Framing guidance**: Document the behavioral change from the user's perspective — what `uf init` does differently — rather than exposing internal `specify init` CLI flags. Users run `uf init`, not `specify init` directly. If the internal invocation is mentioned, frame it as implementation context, not a user-facing command. @@ -56,5 +59,3 @@ The change is scoped to updating existing Markdown content in 3 files. No new pa **Assessment**: PASS The update improves visitor understanding of what `uf init` does during sub-tool initialization. Framing the specify step at the behavioral level (offline, directory-scoped) rather than exposing raw CLI flags serves the visitor's needs without adding implementation noise. - - diff --git a/openspec/changes/fix-specify-init-docs/specs/specify-init-docs.md b/openspec/changes/fix-specify-init-docs/specs/specify-init-docs.md index 65ebd56..9625215 100644 --- a/openspec/changes/fix-specify-init-docs/specs/specify-init-docs.md +++ b/openspec/changes/fix-specify-init-docs/specs/specify-init-docs.md @@ -12,11 +12,13 @@ The Sub-Tool Initialization section of `developer.md` MUST document that `uf ini The documentation MUST NOT present `specify init` as a standalone user-facing command. #### Scenario: Developer reads Sub-Tool Initialization section + - **GIVEN** a developer is reading the "Sub-Tool Initialization" section of `developer.md` - **WHEN** they review the list of sub-tool initialization steps - **THEN** they see specify initialization listed between Dewey initialization and opencode.json configuration, describing that `.specify/` is created with Speckit configuration in offline mode #### Scenario: Developer encounters .specify/ directory after uf init + - **GIVEN** a developer ran `uf init` and sees a `.specify/` directory they didn't expect - **WHEN** they check the developer guide to understand what created it - **THEN** the Sub-Tool Initialization section explains that `uf init` creates `.specify/` for the specification framework @@ -28,6 +30,7 @@ The `init` section of `cli.md` MUST mention that the command also initializes th No new flags SHALL be added to the flag table — `--here`, `--integration`, and `--offline` are internal arguments, not user-facing flags. #### Scenario: Developer looks up uf init in CLI reference + - **GIVEN** a developer is reading the `init` section in the CLI reference - **WHEN** they read the command description - **THEN** the description mentions specify/Speckit initialization alongside the existing scaffolding description @@ -37,6 +40,7 @@ No new flags SHALL be added to the flag table — `--here`, `--integration`, and The sub-tool initialization summary in `common-workflows.md` (line 436) MUST include specify initialization alongside the existing Dewey and opencode.json mentions. #### Scenario: Developer reads the setup flow + - **GIVEN** a developer is following the Environment Setup workflow - **WHEN** they read the `uf init` summary at the end of setup - **THEN** the summary mentions specify initialization alongside Dewey init, config.yaml creation, and opencode.json configuration diff --git a/openspec/changes/framing-enhancements/design.md b/openspec/changes/framing-enhancements/design.md index 936fb9b..744dd66 100644 --- a/openspec/changes/framing-enhancements/design.md +++ b/openspec/changes/framing-enhancements/design.md @@ -5,11 +5,13 @@ Four existing pages need small enhancements to connect them to the harness engin ## Goals / Non-Goals ### Goals + - Add targeted sections/sentences to 4 pages - Use harness engineering as secondary framing, keep existing vocabulary primary - Keep additions concise and high-signal ### Non-Goals + - Rebranding any page - Adding decay warnings to feature pages - Custom HTML or styling diff --git a/openspec/changes/framing-enhancements/proposal.md b/openspec/changes/framing-enhancements/proposal.md index fc228f5..5d40c38 100644 --- a/openspec/changes/framing-enhancements/proposal.md +++ b/openspec/changes/framing-enhancements/proposal.md @@ -14,15 +14,18 @@ GitHub Issue: #95 ## Capabilities ### New Capabilities + - None (enhancements to existing pages) ### Modified Capabilities + - `divisor-page`: Enhanced with architectural rationale section - `constitution-page`: Enhanced with governance hierarchy context - `knowledge-page`: Enhanced with three-tier context framing - `developer-page`: Enhanced with feedforward framing for convention packs ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/gateway-docs/design.md b/openspec/changes/gateway-docs/design.md index 97c34ee..4dcbba3 100644 --- a/openspec/changes/gateway-docs/design.md +++ b/openspec/changes/gateway-docs/design.md @@ -5,6 +5,7 @@ The `uf gateway` command implements an LLM reverse proxy with 3 subcommands and ## Goals / Non-Goals ### Goals + - Document all 3 subcommands with flags and usage - Explain the credential isolation model clearly (this is the primary value proposition) - Document provider auto-detection and priority order @@ -12,6 +13,7 @@ The `uf gateway` command implements an LLM reverse proxy with 3 subcommands and - Document token refresh behavior and sandbox integration ### Non-Goals + - Deep Bedrock SigV4 signing implementation details (internal concern) - Troubleshooting every provider-specific error (add as issues arise) - Performance benchmarks or latency analysis @@ -34,6 +36,7 @@ The `uf gateway` command implements an LLM reverse proxy with 3 subcommands and ## Content Sources Authoritative upstream source files: + - Gateway command: `unbound-force/unbound-force/internal/gateway/` (server, proxy, providers, token refresh) - CLI help: `uf gateway --help`, `uf gateway start --help` - Sandbox integration: `unbound-force/unbound-force/internal/sandbox/` (autoStartGateway) diff --git a/openspec/changes/gateway-docs/proposal.md b/openspec/changes/gateway-docs/proposal.md index 7e0b723..a48c4ee 100644 --- a/openspec/changes/gateway-docs/proposal.md +++ b/openspec/changes/gateway-docs/proposal.md @@ -18,12 +18,15 @@ A new documentation page for the `uf gateway` command covering: ## Capabilities ### New Capabilities + - `docs/reference/gateway`: Comprehensive gateway documentation page ### Modified Capabilities + - None (CLI reference page linkage is handled by the cli-reference-and-positioning change) ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/gateway-docs/tasks.md b/openspec/changes/gateway-docs/tasks.md index cb3db79..e698eeb 100644 --- a/openspec/changes/gateway-docs/tasks.md +++ b/openspec/changes/gateway-docs/tasks.md @@ -33,5 +33,5 @@ - [x] 6.3 Verify page appears in Reference section navigation - [x] 6.4 Verify all internal links resolve (no dead links) - [ ] 6.5 Verify both light and dark mode rendering - - + + diff --git a/openspec/changes/gaze-multi-language-docs/.openspec.yaml b/openspec/changes/gaze-multi-language-docs/.openspec.yaml new file mode 100644 index 0000000..711f289 --- /dev/null +++ b/openspec/changes/gaze-multi-language-docs/.openspec.yaml @@ -0,0 +1,2 @@ +schema: unbound-force +created: 2026-08-23 diff --git a/openspec/changes/gaze-multi-language-docs/design.md b/openspec/changes/gaze-multi-language-docs/design.md new file mode 100644 index 0000000..b27d190 --- /dev/null +++ b/openspec/changes/gaze-multi-language-docs/design.md @@ -0,0 +1,55 @@ +# Design: Gaze Multi-Language Documentation Update + +## Context + +Gaze has expanded from a Go-only tool to a multi-language analysis framework through 4 upstream PRs (gaze#178, gaze#180, gaze#184, gaze#194). The website needs to reflect this evolution across multiple pages while maintaining content accuracy and avoiding overstatement of maturity. + +## Goals + +- Accurately document Gaze's multi-language capabilities without overstating maturity +- Provide clear migration guidance for breaking changes +- Maintain cross-page consistency in the multi-language narrative +- All descriptions sourced from upstream PR descriptions and issue bodies + +## Non-Goals + +- Writing a full external analyzer development tutorial (that belongs in-repo at `docs/protocol.md`) +- Documenting the streaming protocol mode in detail (too implementation-specific for the website) +- Creating a separate "Multi-Language" landing page (not warranted by current maturity) +- Updating the blog posts (they describe Gaze at a point in time and remain accurate for that context) + +## Decisions + +### D1: In-page migration section (not separate page) + +Migration notes for the JSON field rename and coverage behavior change will be added as a `## Migration Notes` section at the bottom of the Gaze project page, before "Learn More." A separate migration guide page would become stale after one release cycle and violate the Zero-Waste Mandate. + +### D2: Taxonomy depth — list by tier, don't reproduce full table + +The expanded taxonomy will list the 10 new universal types by tier (P0, P1, P2) with brief descriptions, then link to `docs/protocol.md` for the full 48-type reference table. Reproducing the full table on the website would create a maintenance burden and risk content drift (R3). + +### D3: Homepage badge — "Go + Multi-Language" + +The Gaze card badge on the homepage will change from "Go" to "Go + Multi-Language" to signal the expanded scope. The card description will not change — it already describes side effects and CRAP scores in language-agnostic terms. Protocol details do not belong on a homepage teaser. + +### D4: `--test-short` in tester guide CI section + +The `--test-short` flag will be documented in the tester guide's CI Integration Pattern section, where users encounter coverage configuration. A migration callout blockquote will alert users to the behavior change. + +### D5: Constitution alignment confirmed + +Observable Quality (Principle III) is the most relevant principle — documenting machine-parseable output changes supports users building integrations. Testability (Principle IV) is PASS per the project's manual validation model. Principles I, II are N/A (no agent changes). Principle V is N/A (no security impact). + +## Risks + +### R1: Upstream PRs not yet merged + +Some upstream PRs (gaze#184, gaze#194) may not be merged when this website change is ready. **Mitigation**: The website change should be merged to `main` only after verifying all upstream PRs are merged. If any PR slips, defer the corresponding documentation sections or use `draft: true`. + +### R2: JSON example accuracy + +The migration notes document field renames and new fields. If the upstream implementation changes field names before merge, the website content becomes inaccurate on day one. **Mitigation**: Document field names and types rather than full JSON examples, reducing the accuracy surface area. Verify against merged code before website merge. + +### R3: Side effect list staleness + +The expanded taxonomy (48 types) will grow as new analyzers are added. **Mitigation**: D2 avoids reproducing the full reference table — the website lists the 10 new universal types and links to `docs/protocol.md` for the authoritative list. This bounds the maintenance obligation to the summary, not the exhaustive reference. diff --git a/openspec/changes/gaze-multi-language-docs/proposal.md b/openspec/changes/gaze-multi-language-docs/proposal.md new file mode 100644 index 0000000..38934c8 --- /dev/null +++ b/openspec/changes/gaze-multi-language-docs/proposal.md @@ -0,0 +1,62 @@ +# Proposal: Gaze Multi-Language Documentation Update + +## Why + +Gaze has evolved from a Go-only test quality analysis tool to a multi-language analysis framework through four upstream PRs: + +- **gaze#178** — External analyzer protocol (JSON-RPC 2.0) with `--analyzer` and `--language` CLI flags, `.gaze.yaml` analyzer configuration, three-tier discovery mechanism +- **gaze#180** — Breaking JSON change: `go_version` renamed to `language_version`, new `language` field, 7 language-neutral `SideEffectType` aliases, streaming protocol mode +- **gaze#184** — Expanded side effect taxonomy: 10 new universal `SideEffectType` constants across P0-P2 tiers, `SideEffect.Detail` metadata field, protocol v1.1.0 +- **gaze#194** — `--test-short` CLI flag, coverage behavior change (full test suite by default), `GAZE_COVERAGE_RUN=1` env var + +The website documentation currently describes Gaze as a Go-only tool and does not reflect these changes. + +## What + +Update the Unbound Force website to accurately document Gaze's multi-language support, new CLI flags, expanded side effect taxonomy, and breaking changes requiring migration guidance. + +### Capabilities + +1. **External Analyzer Protocol Documentation** — New section on the Gaze project page explaining JSON-RPC 2.0 protocol, three-tier discovery, and how to use external analyzers +2. **Migration Notes** — In-page section documenting breaking JSON changes (`go_version` → `language_version`), coverage behavior change, and CRAP score impact +3. **Expanded Taxonomy Documentation** — Updated side effect taxonomy with 10 new universal types listed by tier +4. **CLI Flag Updates** — Three new flags (`--analyzer`, `--language`, `--test-short`) added to the flags table +5. **Cross-Page Consistency** — Homepage card, tester guide, team page, and projects index updated to reflect multi-language framing + +### Impact + +- **`content/docs/projects/gaze.md`** — Primary update target: frontmatter, new sections, updated tables +- **`layouts/home.html`** — Homepage Gaze card badge update +- **`content/docs/getting-started/tester.md`** — `--test-short` documentation, side effect count update +- **`content/_index.md`** — Reviewed; lead text does not reference Go-only analysis. No changes needed +- **`content/docs/team/gaze-tester.md`** — Update framing from "for Go" to multi-language +- **`content/docs/projects/_index.md`** — Update Gaze description from "for Go" to multi-language + +### Tracking + +- GitHub Issue #227 — External analyzer protocol and new CLI flags +- GitHub Issue #228 — Breaking JSON change: `go_version` → `language_version` +- GitHub Issue #229 — Expanded side effect taxonomy: 10 new universal types +- GitHub Issue #230 — `--test-short` flag and coverage behavior change + +## Constitution Alignment + +### I. Autonomous Collaboration + +**Assessment**: N/A — This is a documentation-only change to a static website. No agent collaboration patterns are affected. + +### II. Composability First + +**Assessment**: N/A — No agent, command, or workflow changes are introduced. + +### III. Observable Quality + +**Assessment**: PASS — This change directly supports Observable Quality by documenting Gaze's machine-parseable output changes (JSON field renames, new fields, expanded taxonomy). Users who consume Gaze's JSON output need accurate documentation to build integrations and CI pipelines. The migration notes ensure existing consumers can adapt to breaking changes. + +### IV. Testability + +**Assessment**: PASS — This is a documentation-only change to a static website with no automated test suite. The coverage strategy is manual validation: `npm run build` succeeds (task 4.1), visual verification of all affected pages (task 4.2), content accuracy verification against upstream sources (task 4.3), and upstream PR merge verification (task 4.4). This aligns with the project's validation model defined in AGENTS.md. + +### V. Security by Default + +**Assessment**: N/A — Documentation changes do not introduce dependencies, external inputs, or security-sensitive operations. No CI pipeline changes, no new npm packages, no configuration modifications. diff --git a/openspec/changes/gaze-multi-language-docs/specs/gaze-docs-update.md b/openspec/changes/gaze-multi-language-docs/specs/gaze-docs-update.md new file mode 100644 index 0000000..e20592a --- /dev/null +++ b/openspec/changes/gaze-multi-language-docs/specs/gaze-docs-update.md @@ -0,0 +1,105 @@ +# Spec: Gaze Documentation Update for Multi-Language Support + +## ADDED Requirements + +### External Analyzer Protocol Section + +The Gaze project page MUST include a new section documenting the external analyzer protocol. + +**Scenario**: A user working in Python visits the Gaze project page to evaluate whether Gaze can help with their project. + +- GIVEN a user visiting the Gaze project page +- WHEN they read the External Analyzers section +- THEN the section contains a description of the JSON-RPC 2.0 protocol, the three-tier discovery mechanism (CLI flag, `.gaze.yaml`, PATH convention), and a link to `docs/protocol.md` for the full protocol specification + +### Migration Notes Section + +The Gaze project page MUST include a Migration Notes section documenting breaking changes. + +- GIVEN a user upgrading from a previous version of Gaze +- WHEN they read the Migration Notes section +- THEN the section documents the old field name `go_version`, the new field name `language_version`, the new `language` field, a code-level description of the change, and the 7 language-neutral `SideEffectType` aliases (`AsyncTaskSpawn`, `FFICall`, `ErrorSignal`, `GeneratorYield`, `ContainerMutation`, `StreamOutput`, `ResourceManagement`) + +- GIVEN a user upgrading from a previous version of Gaze +- WHEN they read the Coverage Behavior Change subsection +- THEN the section documents that coverage now reflects the full test suite (not `-short`), the `--test-short` opt-in flag, the `GAZE_COVERAGE_RUN=1` environment variable, and that CRAP scores may change after upgrade + +### Expanded Side Effect Taxonomy + +The Gaze project page MUST document the expanded side effect taxonomy with universal types. + +- GIVEN a user reviewing Gaze's side effect detection capabilities +- WHEN they read the Universal Side Effect Types subsection +- THEN the section lists the new universal types by tier: `ErrorSignal` (P0), `GeneratorYield`/`ContainerMutation`/`StreamOutput` (P1), and P2 universal types, with a link to protocol documentation for the complete reference + +The specific type names MUST be sourced from the merged upstream PR (gaze#184); the names listed here are representative of the expected taxonomy at time of writing. + +### Tester Guide `--test-short` Documentation + +The tester guide MUST document the `--test-short` flag in the CI Integration Pattern section. + +- GIVEN a user configuring Gaze in their CI pipeline +- WHEN they read the CI Integration Pattern section +- THEN the section documents `--test-short` as an optional flag with a migration callout explaining the coverage behavior change and a link to the Gaze migration notes + +## MODIFIED Requirements + +### Project Description and Framing + +The Gaze project page description MUST be updated to reflect multi-language support. The description MUST NOT overstate maturity — Go is the primary supported language, and multi-language support is via the external analyzer protocol. + +- GIVEN a user evaluating Gaze for a non-Go project +- WHEN they read the project description and lead text +- THEN the description explicitly states Go is the primary supported language and other languages are supported via the external analyzer protocol + +### CLI Flags Table + +The CLI flags table MUST be updated to include the three new flags. + +- GIVEN a user looking up available CLI flags +- WHEN they view the CLI flags table +- THEN they see all current flags including `--analyzer ` (crap/quality/report), `--language ` (crap/quality/report), and `--test-short` (crap/report/self-check) + +### Architecture Table + +The architecture table MUST be updated to reflect any new packages added for multi-language support, if such packages exist in the upstream codebase. If no new packages exist, no update is needed. The table MUST remain accurate against the upstream codebase. + +- GIVEN a developer reviewing Gaze's architecture +- WHEN they view the architecture package table +- THEN it accurately reflects the current package structure including any new packages for external analyzer support + +### Homepage Card + +The homepage Gaze card badge MUST be updated to reflect multi-language support. + +- GIVEN a visitor browsing the Unbound Force homepage +- WHEN they see the Gaze project card +- THEN the badge and description reflect Gaze's expanded scope beyond Go-only analysis + +### Tester Guide Side Effect Count Consistency + +The tester guide's side effect count MUST be updated to be consistent with the expanded taxonomy on the project page. + +- GIVEN a user reading both the tester guide and the project page +- WHEN they compare side effect counts +- THEN the numbers are consistent and not contradictory + +### Related Pages Multi-Language Framing + +The team page (`gaze-tester.md`) and projects index page (`_index.md`) MUST be updated to reflect multi-language framing consistent with the project page. + +- GIVEN a user navigating from the projects index or team page to the Gaze project page +- WHEN they compare the Gaze descriptions +- THEN the framing is consistent with the updated project page (no "for Go" framing that contradicts multi-language support) + +### Current Limitations Section Accuracy + +The Current Limitations section MUST be reviewed and updated for accuracy against the expanded taxonomy. + +- GIVEN a user reading the Current Limitations section +- WHEN they compare the stated limitations with the expanded taxonomy documented elsewhere on the page +- THEN all stated limitations remain accurate and are not contradicted by the new content (e.g., P3-P4 limitation is scoped to Go analysis, external analyzer scope is noted) + +## REMOVED Requirements + +None. diff --git a/openspec/changes/gaze-multi-language-docs/tasks.md b/openspec/changes/gaze-multi-language-docs/tasks.md new file mode 100644 index 0000000..4719b52 --- /dev/null +++ b/openspec/changes/gaze-multi-language-docs/tasks.md @@ -0,0 +1,31 @@ +# Tasks: Gaze Multi-Language Documentation Update + +## Group 1: Update Gaze Project Page (`content/docs/projects/gaze.md`) — Sequential + +- [x] 1.1 Update frontmatter: revise `description` and `lead` to replace "for Go" with multi-language framing (Issue #227) +- [x] 1.2 Add External Analyzers section after CLI Flags: document JSON-RPC 2.0 protocol, three-tier discovery (CLI flag → `.gaze.yaml` → PATH convention), `--language` flag, link to `docs/protocol.md`, mention streaming mode (Issue #227) +- [x] 1.3 Update CLI flags table: add `--analyzer ` (crap/quality/report), `--language ` (crap/quality/report), `--test-short` (crap/report/self-check) (Issues #227, #230) +- [x] 1.4 Expand side effect taxonomy: add Universal Side Effect Types subsection listing 10 new types by tier — `ErrorSignal` (P0); `GeneratorYield`, `ContainerMutation`, `StreamOutput` (P1); `AsyncGeneratorYield`, `MetaprogrammingMutation`, `DescriptorEffect`, `ResourceManagement`, `ImportSideEffect`, `MonkeyPatch` (P2). Document `Detail` metadata field. Link to protocol docs for complete reference. Do not reproduce the full 48-type reference table — link to protocol docs instead (Issue #229) +- [x] 1.5 Update architecture package table: verify against upstream codebase and add any new packages (e.g., `protocol`, `provider`, `adapter`, `cliutil`) (Issue #227) +- [x] 1.6 Add Migration Notes section before "Learn More": (a) JSON Output Changes — `go_version` → `language_version`, new `language` field (Issue #228); (b) 7 language-neutral `SideEffectType` aliases (Issue #228); (c) Coverage Behavior Change — full test suite default, `--test-short` opt-in, `GAZE_COVERAGE_RUN=1`, CRAP score impact (Issue #230); (d) CRAP score changes users may observe after upgrade (Issue #230) +- [x] 1.7 Review and update the "Current Limitations" section for accuracy against the expanded taxonomy — scope P3-P4 limitation to "(Go analysis)", note external analyzers define their own detection scope + +## Group 2: Update Homepage (`layouts/home.html`) — Parallel + +- [x] 2.1 [P] Update Gaze card badge from "Go" to "Go + Multi-Language" (Issue #227) + +## Group 3: Update Tester Guide and Related Pages — Parallel + +- [x] 3.1 [P] Update tester guide (`content/docs/getting-started/tester.md`): add `--test-short` migration callout in CI section, add `--test-short` example in CI code block, update side effects count from "30+ types" to reflect the expanded taxonomy for consistency with the project page (Issues #228, #230) +- [x] 3.2 [P] Update `content/docs/team/gaze-tester.md`: revise framing from "for Go" to multi-language, add reference to external analyzer protocol (Issue #227) +- [x] 3.3 [P] Update `content/docs/projects/_index.md`: revise Gaze description from "for Go" to multi-language framing (Issue #227) + +## Group 4: Verification + +- [x] 4.1 Run `npm run build` — must succeed with no new warnings +- [x] 4.2 Visual verification: (a) all new sections render on Gaze project page, (b) homepage card shows updated badge, (c) tester guide shows `--test-short` docs, (d) team page and projects index show updated framing, (e) all internal links resolve, (f) dark mode renders correctly on the three modified pages (Gaze project page, homepage, tester guide) +- [x] 4.3 Constitution alignment verification — verify that all CLI flag names, JSON field names, and side effect type names documented on the updated pages match the upstream Gaze codebase. Cross-reference against PR descriptions for gaze#178, gaze#180, gaze#184, gaze#194 +- [x] 4.4 Upstream PR merge verification gate — verify all four upstream PRs (gaze#178, gaze#180, gaze#184, gaze#194) are merged before proceeding to merge the website PR. If any PR is not merged, defer the corresponding documentation sections + + + diff --git a/openspec/changes/init-setup-error-docs/design.md b/openspec/changes/init-setup-error-docs/design.md index b87faa4..9f466d7 100644 --- a/openspec/changes/init-setup-error-docs/design.md +++ b/openspec/changes/init-setup-error-docs/design.md @@ -7,11 +7,13 @@ The website's CLI reference (`content/docs/reference/cli.md`) and developer guid ## Goals / Non-Goals ### Goals + - Add error output behavior documentation to the `init` and `setup` sections of the CLI reference page - Add an error output note to the Sub-Tool Initialization section of the developer guide - Keep additions minimal — one sentence per location ### Non-Goals + - Creating a changelog or release notes infrastructure (no such infrastructure exists; tracked separately) - Adding troubleshooting pages (no existing troubleshooting content references the old generic error messages — confirmed by triage search) - Documenting specific error messages or failure modes (error output is tool-dependent and varies) diff --git a/openspec/changes/init-setup-error-docs/proposal.md b/openspec/changes/init-setup-error-docs/proposal.md index 5081b88..e724c10 100644 --- a/openspec/changes/init-setup-error-docs/proposal.md +++ b/openspec/changes/init-setup-error-docs/proposal.md @@ -17,13 +17,16 @@ Two small documentation updates: ## Capabilities ### New Capabilities + - None ### Modified Capabilities + - `docs/reference/cli`: `init` and `setup` sections updated with error reporting behavior - `docs/getting-started/developer`: Sub-Tool Initialization section updated with error output note ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/messaging-reframe/design.md b/openspec/changes/messaging-reframe/design.md index 2f37f97..4551c80 100644 --- a/openspec/changes/messaging-reframe/design.md +++ b/openspec/changes/messaging-reframe/design.md @@ -7,12 +7,14 @@ The proposal (proposal.md) established constitution alignment: Content Accuracy ## Goals / Non-Goals ### Goals + - Add one feature card to the homepage "Why Unbound Force?" section - Add a "Design Philosophy" section to the getting-started index page - Use harness engineering as secondary framing, superhero identity stays primary - Attribute any Liu article data points to their source ### Non-Goals + - Rebranding the homepage or site around harness engineering - Adding custom CSS or new visual elements - Modifying the hero section, project cards, or other existing content @@ -24,7 +26,7 @@ The proposal (proposal.md) established constitution alignment: Content Accuracy **Card content**: "Built as a Harness, Not a Wrapper" — feedforward controls guide agents before they write code, feedback controls catch what slips through. This conveys the core architectural concept without requiring knowledge of Liu's article. -**Design philosophy section**: Add after the "Get Started" section in _index.md. Three paragraphs: the Agent = Model + Harness equation, the three-tier context system, and layered feedback. Link to the architecture page only if it exists on this branch (it won't — #88 is a separate PR). +**Design philosophy section**: Add after the "Get Started" section in \_index.md. Three paragraphs: the Agent = Model + Harness equation, the three-tier context system, and layered feedback. Link to the architecture page only if it exists on this branch (it won't — #88 is a separate PR). ## Risks / Trade-offs diff --git a/openspec/changes/messaging-reframe/proposal.md b/openspec/changes/messaging-reframe/proposal.md index 449a1e3..b5956f1 100644 --- a/openspec/changes/messaging-reframe/proposal.md +++ b/openspec/changes/messaging-reframe/proposal.md @@ -13,13 +13,16 @@ GitHub Issue: #90 ## Capabilities ### New Capabilities + - `homepage-harness-card`: A feature card on the homepage that speaks to the harness engineering audience - `getting-started-design-philosophy`: A section on the getting-started index page explaining the design philosophy ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/quality-gates-page/design.md b/openspec/changes/quality-gates-page/design.md index 39bf909..91e1e8d 100644 --- a/openspec/changes/quality-gates-page/design.md +++ b/openspec/changes/quality-gates-page/design.md @@ -5,12 +5,14 @@ Quality information is scattered across 5 pages. Issue #94 calls for a consolida ## Goals / Non-Goals ### Goals + - Present the 4-layer feedback stack in order (CI → Gaze → Divisor Council → Constitution Check) - Explain computational-first, inferential-second ordering - Cover gatekeeping value protection, doer/judge separation, 3-iteration cap - Link to existing pages for deeper detail on individual components ### Non-Goals + - Duplicating content from the-divisor.md or tester.md - Adding custom HTML or styling - Modifying existing pages diff --git a/openspec/changes/quality-gates-page/proposal.md b/openspec/changes/quality-gates-page/proposal.md index 2180dfd..55d675f 100644 --- a/openspec/changes/quality-gates-page/proposal.md +++ b/openspec/changes/quality-gates-page/proposal.md @@ -11,12 +11,15 @@ GitHub Issue: #94 ## Capabilities ### New Capabilities + - `quality-gates-page`: Documentation page covering the layered quality feedback stack, gatekeeping value protection, doer/judge separation, and the 3-iteration review cap ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/sandbox-docs/design.md b/openspec/changes/sandbox-docs/design.md index 9d23324..78136ee 100644 --- a/openspec/changes/sandbox-docs/design.md +++ b/openspec/changes/sandbox-docs/design.md @@ -5,6 +5,7 @@ The `uf sandbox` command surface spans 7 subcommands across three capability tie ## Goals / Non-Goals ### Goals + - Create a single, comprehensive sandbox documentation page covering all three capability tiers - Include platform-specific setup instructions (macOS Podman machine, Fedora SELinux) - Document the security model (rootless Podman, read-only mounts, no push credentials) @@ -12,6 +13,7 @@ The `uf sandbox` command surface spans 7 subcommands across three capability tie - Label CDE backend as experimental with appropriate caveats ### Non-Goals + - Tutorial-style walkthrough (covered by blog post #40) - Container image customization guide (separate concern, references containerfile repo) - Gateway integration details (covered by gateway-docs change) @@ -36,6 +38,7 @@ The `uf sandbox` command surface spans 7 subcommands across three capability tie ## Content Sources Authoritative upstream source files: + - Sandbox core: `unbound-force/unbound-force/internal/sandbox/` (sandbox.go, backend.go, podman.go, workspace.go, git_sync.go) - CLI commands: `unbound-force/unbound-force/cmd/unbound-force/sandbox.go` and subcommand files - CLI help: `uf sandbox --help`, `uf sandbox --help` diff --git a/openspec/changes/sandbox-docs/proposal.md b/openspec/changes/sandbox-docs/proposal.md index 796fda8..3f26b98 100644 --- a/openspec/changes/sandbox-docs/proposal.md +++ b/openspec/changes/sandbox-docs/proposal.md @@ -17,15 +17,18 @@ This change addresses GitHub issues [#39](https://github.com/unbound-force/websi ## Capabilities ### New Capabilities + - `docs/reference/sandbox`: Comprehensive sandbox documentation page covering all subcommands, modes, and platform setup - UID mapping prerequisites and troubleshooting section - Persistent workspace lifecycle documentation - CDE backend documentation (experimental label) ### Modified Capabilities + - CLI reference page (from `cli-reference-and-positioning` change): sandbox entry links to detailed docs ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/sandbox-docs/tasks.md b/openspec/changes/sandbox-docs/tasks.md index 7cb3922..7ff7c4e 100644 --- a/openspec/changes/sandbox-docs/tasks.md +++ b/openspec/changes/sandbox-docs/tasks.md @@ -39,5 +39,5 @@ - [ ] 6.3 Run `npm run dev` and verify sandbox page renders correctly with all sections - [x] 6.4 Verify page appears in Reference section navigation - [ ] 6.5 Verify both light and dark mode rendering - - + + diff --git a/openspec/changes/tutorial-code-review/design.md b/openspec/changes/tutorial-code-review/design.md index e1cab24..58438f5 100644 --- a/openspec/changes/tutorial-code-review/design.md +++ b/openspec/changes/tutorial-code-review/design.md @@ -5,6 +5,7 @@ The website has reference documentation for both review commands in `common-work ## Goals / Non-Goals ### Goals + - Create a step-by-step tutorial covering both review commands in sequence - Show expected output at each step (fenced `text` code blocks) - Include the decision table for quick command selection @@ -12,6 +13,7 @@ The website has reference documentation for both review commands in `common-work - Cover CI causality analysis with a concrete example ### Non-Goals + - Duplicate the full command reference (flags, phases) — link to common-workflows docs - Duplicate the blog post's narrative on CI causality — link to the blog post - Cover Gaze integration in depth (optional feature, not required for the tutorial) @@ -34,6 +36,7 @@ The website has reference documentation for both review commands in `common-work ## Content Sources Authoritative upstream sources: + - `/review-council`: `unbound-force/unbound-force/.opencode/command/review-council.md` - `/review-pr`: `unbound-force/unbound-force/.opencode/command/review-pr.md` - Comparison table: `content/docs/getting-started/common-workflows.md` (if PR #74 merged) diff --git a/openspec/changes/tutorial-code-review/proposal.md b/openspec/changes/tutorial-code-review/proposal.md index 4939002..4212f30 100644 --- a/openspec/changes/tutorial-code-review/proposal.md +++ b/openspec/changes/tutorial-code-review/proposal.md @@ -19,12 +19,15 @@ A new tutorial page at `content/docs/getting-started/code-review-tutorial.md` co ## Capabilities ### New Capabilities + - `docs/getting-started/code-review-tutorial`: Tutorial page for the complete code review lifecycle ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/tutorial-code-review/tasks.md b/openspec/changes/tutorial-code-review/tasks.md index 157161b..ba724c9 100644 --- a/openspec/changes/tutorial-code-review/tasks.md +++ b/openspec/changes/tutorial-code-review/tasks.md @@ -27,5 +27,5 @@ - [x] 5.4 Verify all internal links resolve (no dead links) - [ ] 5.5 Run `npm run dev` and verify the tutorial renders correctly - [ ] 5.6 Verify both light and dark mode rendering - - + + diff --git a/openspec/changes/tutorial-config/design.md b/openspec/changes/tutorial-config/design.md index 6cd86dd..a51078a 100644 --- a/openspec/changes/tutorial-config/design.md +++ b/openspec/changes/tutorial-config/design.md @@ -5,12 +5,14 @@ The website has a config reference page (PR #75) covering the command surface, l ## Goals / Non-Goals ### Goals + - Create a hands-on tutorial for common customization scenarios - Show `uf config init` → edit → `uf config validate` → `uf config show` workflow - Include platform-specific examples (Fedora/RHEL, macOS, custom embedding models) - Demonstrate precedence with a concrete override scenario ### Non-Goals + - Duplicate the full config reference (all 7 sections in detail) — link to the reference page - Cover every config key — focus on the most commonly customized settings - Cover sandbox or gateway config in depth (those have their own reference pages) @@ -30,6 +32,7 @@ The website has a config reference page (PR #75) covering the command surface, l ## Content Sources Authoritative upstream sources: + - Config implementation: `unbound-force/unbound-force/internal/config/config.go` - CLI help: `uf config --help`, `uf config init --help`, `uf config show --help`, `uf config validate --help` - Config reference page: `content/docs/reference/config.md` (if PR #75 merged) diff --git a/openspec/changes/tutorial-config/proposal.md b/openspec/changes/tutorial-config/proposal.md index 4493481..564e121 100644 --- a/openspec/changes/tutorial-config/proposal.md +++ b/openspec/changes/tutorial-config/proposal.md @@ -18,12 +18,15 @@ A new tutorial page at `content/docs/getting-started/config-tutorial.md` coverin ## Capabilities ### New Capabilities + - `docs/getting-started/config-tutorial`: Tutorial page for environment customization with uf config ### Modified Capabilities + - None ### Removed Capabilities + - None ## Impact diff --git a/openspec/changes/tutorial-config/tasks.md b/openspec/changes/tutorial-config/tasks.md index 6e88f69..0ce96ea 100644 --- a/openspec/changes/tutorial-config/tasks.md +++ b/openspec/changes/tutorial-config/tasks.md @@ -28,5 +28,5 @@ - [x] 5.4 Verify all internal links resolve (no dead links) - [ ] 5.5 Run `npm run dev` and verify the tutorial renders correctly - [ ] 5.6 Verify both light and dark mode rendering - - + + diff --git a/openspec/schemas/unbound-force/schema.yaml b/openspec/schemas/unbound-force/schema.yaml index 9e3a612..5356e8d 100644 --- a/openspec/schemas/unbound-force/schema.yaml +++ b/openspec/schemas/unbound-force/schema.yaml @@ -74,4 +74,5 @@ apply: task as you complete it. Verify that the implementation maintains constitution alignment as documented in the proposal. + # scaffolded by uf vdev diff --git a/openspec/schemas/unbound-force/templates/design.md b/openspec/schemas/unbound-force/templates/design.md index 2165de3..931c626 100644 --- a/openspec/schemas/unbound-force/templates/design.md +++ b/openspec/schemas/unbound-force/templates/design.md @@ -5,9 +5,11 @@ ## Goals / Non-Goals ### Goals + - ### Non-Goals + - ## Decisions diff --git a/openspec/schemas/unbound-force/templates/proposal.md b/openspec/schemas/unbound-force/templates/proposal.md index 45d5fa9..31980e1 100644 --- a/openspec/schemas/unbound-force/templates/proposal.md +++ b/openspec/schemas/unbound-force/templates/proposal.md @@ -9,12 +9,15 @@ ## Capabilities ### New Capabilities + - ``: ### Modified Capabilities + - ``: ### Removed Capabilities + - ``: ## Impact diff --git a/openspec/schemas/unbound-force/templates/spec.md b/openspec/schemas/unbound-force/templates/spec.md index 7b1e55a..796bec1 100644 --- a/openspec/schemas/unbound-force/templates/spec.md +++ b/openspec/schemas/unbound-force/templates/spec.md @@ -5,6 +5,7 @@ #### Scenario: + - **GIVEN** - **WHEN** - **THEN** diff --git a/specs/001-site-scaffold/data-model.md b/specs/001-site-scaffold/data-model.md index 0cc7486..e23a506 100644 --- a/specs/001-site-scaffold/data-model.md +++ b/specs/001-site-scaffold/data-model.md @@ -10,17 +10,17 @@ This is a static Hugo website with no database, API, or dynamic data layer. The ### 1. Hugo Site Configuration (`hugo.toml`) -| Field | Type | Required | Value | -|-------|------|----------|-------| -| `title` | string | yes | `"Unbound Force"` | -| `baseurl` | string | yes | `"https://unboundforce.dev/"` | -| `disableAliases` | bool | yes | `true` | -| `disableHugoGeneratorInject` | bool | yes | `true` | -| `enableEmoji` | bool | yes | `true` | -| `enableGitInfo` | bool | yes | `false` | -| `enableRobotsTXT` | bool | yes | `true` | -| `languageCode` | string | yes | `"en-US"` | -| `copyRight` | string | yes | `"Copyright (c) 2025-2026 Unbound Force"` | +| Field | Type | Required | Value | +| ---------------------------- | ------ | -------- | ----------------------------------------- | +| `title` | string | yes | `"Unbound Force"` | +| `baseurl` | string | yes | `"https://unboundforce.dev/"` | +| `disableAliases` | bool | yes | `true` | +| `disableHugoGeneratorInject` | bool | yes | `true` | +| `enableEmoji` | bool | yes | `true` | +| `enableGitInfo` | bool | yes | `false` | +| `enableRobotsTXT` | bool | yes | `true` | +| `languageCode` | string | yes | `"en-US"` | +| `copyRight` | string | yes | `"Copyright (c) 2025-2026 Unbound Force"` | **Outputs**: `home = ["HTML", "RSS", "searchIndex"]`, `section = ["HTML", "RSS", "SITEMAP"]` @@ -28,18 +28,18 @@ This is a static Hugo website with no database, API, or dynamic data layer. The ### 2. Doks Theme Parameters (`params.toml`) -| Field | Type | Required | Value | -|-------|------|----------|-------| -| `title` | string | yes | `"Unbound Force"` | -| `description` | string | yes | Site-wide meta description | -| `[doks].colorMode` | string | yes | `"auto"` | -| `[doks].navbarSticky` | bool | yes | `true` | -| `[doks].flexSearch` | bool | yes | `true` | -| `[doks].docsRepo` | string | yes | `"https://github.com/unbound-force/website"` | -| `[doks].textDark` | string | yes | `"#e2e8f0"` | -| `[doks].accentDark` | string | yes | `"#818cf8"` | -| `[doks].textLight` | string | yes | `"#0f172a"` | -| `[doks].accentLight` | string | yes | `"#3b82f6"` | +| Field | Type | Required | Value | +| --------------------- | ------ | -------- | -------------------------------------------- | +| `title` | string | yes | `"Unbound Force"` | +| `description` | string | yes | Site-wide meta description | +| `[doks].colorMode` | string | yes | `"auto"` | +| `[doks].navbarSticky` | bool | yes | `true` | +| `[doks].flexSearch` | bool | yes | `true` | +| `[doks].docsRepo` | string | yes | `"https://github.com/unbound-force/website"` | +| `[doks].textDark` | string | yes | `"#e2e8f0"` | +| `[doks].accentDark` | string | yes | `"#818cf8"` | +| `[doks].textLight` | string | yes | `"#0f172a"` | +| `[doks].accentLight` | string | yes | `"#3b82f6"` | **Relationships**: Consumed by Doks theme partials. Colors flow through to Bootstrap CSS variables. @@ -47,31 +47,31 @@ This is a static Hugo website with no database, API, or dynamic data layer. The **Menu Types**: -| Menu | Purpose | Entries | -|------|---------|---------| -| `[[main]]` | Top navbar | Docs link | -| `[[social]]` | Social icons | GitHub org link | -| `[[docs]]` | Sidebar navigation | Getting Started, Projects, Team, Contributing | -| `[[footer]]` | Footer links | As needed | +| Menu | Purpose | Entries | +| ------------ | ------------------ | --------------------------------------------- | +| `[[main]]` | Top navbar | Docs link | +| `[[social]]` | Social icons | GitHub org link | +| `[[docs]]` | Sidebar navigation | Getting Started, Projects, Team, Contributing | +| `[[footer]]` | Footer links | As needed | **Entry Schema**: -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | yes | Display label | -| `url` | string | yes | Target path or URL | -| `weight` | int | yes | Sort order (lower = higher position) | -| `identifier` | string | for `[[docs]]` | Unique ID for sidebar section | +| Field | Type | Required | Description | +| ------------ | ------ | -------------- | ------------------------------------ | +| `name` | string | yes | Display label | +| `url` | string | yes | Target path or URL | +| `weight` | int | yes | Sort order (lower = higher position) | +| `identifier` | string | for `[[docs]]` | Unique ID for sidebar section | ### 4. Homepage Frontmatter (`content/_index.md`) -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `title` | string | yes | Page title (used in `` and hero) | -| `description` | string | yes | Meta description for SEO | -| `lead` | string | yes | Subtitle text displayed in hero section | -| `date` | datetime | yes | Publication date | -| `draft` | bool | yes | Must be `false` for production | +| Field | Type | Required | Description | +| ------------- | -------- | -------- | --------------------------------------- | +| `title` | string | yes | Page title (used in `<title>` and hero) | +| `description` | string | yes | Meta description for SEO | +| `lead` | string | yes | Subtitle text displayed in hero section | +| `date` | datetime | yes | Publication date | +| `draft` | bool | yes | Must be `false` for production | **Relationships**: Consumed by `layouts/home.html`. The `title` and `lead` fields are rendered in the hero section via `{{ .Title }}` and `{{ .Params.lead }}`. @@ -81,28 +81,28 @@ The template does not consume external data files. All content is hardcoded in t **Feature Card** (repeated 4x): -| Field | Type | Description | -|-------|------|-------------| -| Icon | SVG reference | Tabler icon name | -| Title | string | Feature name | -| Description | string | 1-2 sentence explanation | +| Field | Type | Description | +| ----------- | ------------- | ------------------------ | +| Icon | SVG reference | Tabler icon name | +| Title | string | Feature name | +| Description | string | 1-2 sentence explanation | **Project Card** (repeated 1x for Gaze): -| Field | Type | Description | -|-------|------|-------------| -| Icon | SVG reference | Project icon | -| Title | string | Project name ("Gaze") | -| Description | string | Accurate summary from repository | -| Link | string | URL to project page or repository | +| Field | Type | Description | +| ----------- | ------------- | --------------------------------- | +| Icon | SVG reference | Project icon | +| Title | string | Project name ("Gaze") | +| Description | string | Accurate summary from repository | +| Link | string | URL to project page or repository | ### 6. Brand Colors (SCSS Variables) -| Variable | Light Mode | Dark Mode | -|----------|-----------|-----------| -| Primary | `#3b82f6` (electric blue) | -- | -| Accent | `#8b5cf6` (violet) | `#818cf8` (lighter violet) | -| Text | `#0f172a` (slate-900) | `#e2e8f0` (slate-200) | +| Variable | Light Mode | Dark Mode | +| -------- | ------------------------- | -------------------------- | +| Primary | `#3b82f6` (electric blue) | -- | +| Accent | `#8b5cf6` (violet) | `#818cf8` (lighter violet) | +| Text | `#0f172a` (slate-900) | `#e2e8f0` (slate-200) | **Relationships**: Defined in `_variables-custom.scss` as Bootstrap variable overrides (`$primary`). Also set in `params.toml` for Doks theme integration. diff --git a/specs/001-site-scaffold/plan.md b/specs/001-site-scaffold/plan.md index aef0560..b7fd61a 100644 --- a/specs/001-site-scaffold/plan.md +++ b/specs/001-site-scaffold/plan.md @@ -22,15 +22,15 @@ Build the complete Hugo + Doks/Thulite site infrastructure from scratch: package ## Constitution Check -*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* +_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._ ### Pre-Phase 0 Gate -| Principle | Status | Assessment | -|-----------|--------|------------| -| I. Content Accuracy | PASS | The Gaze project card description will be derived from the actual Gaze repository README. Research confirms Gaze does P0-P2 side effect detection and CRAP scoring for Go. GazeCRAP (contract-aware coverage) is NOT yet implemented and MUST NOT be claimed. No placeholder or "Coming Soon" content will be created. | -| II. Minimal Footprint | PASS | The implementation mirrors the complytime-website reference (proven minimal stack). Custom code is limited to `layouts/home.html` (required since Doks has no homepage out of the box), two SCSS files (brand colors + homepage card styles), and standard Hugo config. No additional npm dependencies beyond what complytime-website uses. No blog, analytics, or ancillary features. | -| III. Visitor Clarity | PASS | The homepage follows a clear 4-section structure (hero, features, projects, CTA) designed for immediate comprehension. Navigation menus provide two-click access to all content sections. Information hierarchy flows homepage -> projects -> detailed docs as required. | +| Principle | Status | Assessment | +| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| I. Content Accuracy | PASS | The Gaze project card description will be derived from the actual Gaze repository README. Research confirms Gaze does P0-P2 side effect detection and CRAP scoring for Go. GazeCRAP (contract-aware coverage) is NOT yet implemented and MUST NOT be claimed. No placeholder or "Coming Soon" content will be created. | +| II. Minimal Footprint | PASS | The implementation mirrors the complytime-website reference (proven minimal stack). Custom code is limited to `layouts/home.html` (required since Doks has no homepage out of the box), two SCSS files (brand colors + homepage card styles), and standard Hugo config. No additional npm dependencies beyond what complytime-website uses. No blog, analytics, or ancillary features. | +| III. Visitor Clarity | PASS | The homepage follows a clear 4-section structure (hero, features, projects, CTA) designed for immediate comprehension. Navigation menus provide two-click access to all content sections. Information hierarchy flows homepage -> projects -> detailed docs as required. | **Gate result: ALL PASS. Proceeding to Phase 0.** @@ -85,20 +85,20 @@ website/ > No constitution violations detected. Table intentionally empty. -| Violation | Why Needed | Simpler Alternative Rejected Because | -|-----------|------------|-------------------------------------| -| Custom `layouts/home.html` | Doks does not provide a homepage layout; only docs pages | No simpler alternative exists -- a custom homepage template is the standard Doks pattern | -| Custom `_custom.scss` | Homepage cards/sections need styling not provided by Doks theme | Using inline styles would be harder to maintain and violate Doks conventions | -| `module.toml` with explicit mounts | Required to wire Thulite npm packages into Hugo and exclude Doks' default home.html | This is the documented Thulite/Doks architecture, not a custom workaround | +| Violation | Why Needed | Simpler Alternative Rejected Because | +| ---------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Custom `layouts/home.html` | Doks does not provide a homepage layout; only docs pages | No simpler alternative exists -- a custom homepage template is the standard Doks pattern | +| Custom `_custom.scss` | Homepage cards/sections need styling not provided by Doks theme | Using inline styles would be harder to maintain and violate Doks conventions | +| `module.toml` with explicit mounts | Required to wire Thulite npm packages into Hugo and exclude Doks' default home.html | This is the documented Thulite/Doks architecture, not a custom workaround | ## Constitution Check — Post-Design Re-Evaluation -*Re-check after Phase 1 design completion.* +_Re-check after Phase 1 design completion._ -| Principle | Status | Post-Design Assessment | -|-----------|--------|------------------------| -| I. Content Accuracy | PASS | Research verified Gaze's actual capabilities (P0-P2 side effects, CRAP scores). Plan explicitly excludes GazeCRAP and unimplemented features. Homepage content derived from verified repository facts. No placeholder content created. | -| II. Minimal Footprint | PASS | Custom code limited to: 1 template (home.html — required, Doks has no homepage), 2 SCSS files (brand colors + card styles), standard Hugo config + module.toml (standard Thulite architecture). No additional npm dependencies. No blog, analytics, or ancillary features. | -| III. Visitor Clarity | PASS | Homepage 4-section structure (hero → features → projects → CTA) provides immediate comprehension. Navigation menus enable two-click access to all sections. Information hierarchy flows homepage → projects → detailed docs. | +| Principle | Status | Post-Design Assessment | +| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| I. Content Accuracy | PASS | Research verified Gaze's actual capabilities (P0-P2 side effects, CRAP scores). Plan explicitly excludes GazeCRAP and unimplemented features. Homepage content derived from verified repository facts. No placeholder content created. | +| II. Minimal Footprint | PASS | Custom code limited to: 1 template (home.html — required, Doks has no homepage), 2 SCSS files (brand colors + card styles), standard Hugo config + module.toml (standard Thulite architecture). No additional npm dependencies. No blog, analytics, or ancillary features. | +| III. Visitor Clarity | PASS | Homepage 4-section structure (hero → features → projects → CTA) provides immediate comprehension. Navigation menus enable two-click access to all sections. Information hierarchy flows homepage → projects → detailed docs. | **Post-design gate result: ALL PASS. No new violations introduced by design decisions.** diff --git a/specs/001-site-scaffold/quickstart.md b/specs/001-site-scaffold/quickstart.md index 5ded683..c42cf7b 100644 --- a/specs/001-site-scaffold/quickstart.md +++ b/specs/001-site-scaffold/quickstart.md @@ -25,12 +25,12 @@ npm run dev ## Available Commands -| Command | Purpose | -|---------|---------| -| `npm run dev` | Start dev server with live reload at localhost:1313 | -| `npm run build` | Production build (output in `public/`) | -| `npm run preview` | Preview production build locally | -| `npm run format` | Format all files with Prettier | +| Command | Purpose | +| ----------------- | --------------------------------------------------- | +| `npm run dev` | Start dev server with live reload at localhost:1313 | +| `npm run build` | Production build (output in `public/`) | +| `npm run preview` | Preview production build locally | +| `npm run format` | Format all files with Prettier | ## Project Layout @@ -44,17 +44,18 @@ static/ Favicons, CNAME file ## Key Files to Modify -| Task | File(s) | -|------|---------| -| Change site title or base URL | `config/_default/hugo.toml` | -| Change brand colors | `config/_default/params.toml` + `assets/scss/common/_variables-custom.scss` | -| Edit homepage content | `layouts/home.html` (template) + `content/_index.md` (frontmatter) | -| Edit navigation | `config/_default/menus/menus.en.toml` | -| Add custom styles | `assets/scss/common/_custom.scss` | +| Task | File(s) | +| ----------------------------- | --------------------------------------------------------------------------- | +| Change site title or base URL | `config/_default/hugo.toml` | +| Change brand colors | `config/_default/params.toml` + `assets/scss/common/_variables-custom.scss` | +| Edit homepage content | `layouts/home.html` (template) + `content/_index.md` (frontmatter) | +| Edit navigation | `config/_default/menus/menus.en.toml` | +| Add custom styles | `assets/scss/common/_custom.scss` | ## Deployment Automatic via GitHub Actions on push to `main`: + 1. Workflow installs Node.js 22 + Hugo 0.155.1 (extended) 2. Runs `npm ci` then `hugo --minify --gc` 3. Deploys `public/` to GitHub Pages diff --git a/specs/001-site-scaffold/research.md b/specs/001-site-scaffold/research.md index 3628075..2277f7b 100644 --- a/specs/001-site-scaffold/research.md +++ b/specs/001-site-scaffold/research.md @@ -5,18 +5,22 @@ ## 1. Reference Implementation (complytime-website) ### Decision + Mirror the complytime-website (`complytime/website`, branch `feat/website-minimal`) architecture exactly, adapting only content, colors, and domain-specific values. ### Rationale + The complytime-website is a near-identical use case (open source org, Go tool repos, docs-heavy, Hugo + Doks). It is a proven, working implementation that has already solved the Thulite/Doks integration challenges (module mounts, homepage override, GitHub Pages deployment). Reusing this pattern eliminates guesswork. ### Alternatives Considered + - **Start from Doks quickstart**: Would require discovering module mount patterns, homepage override approach, and CI workflow independently. Higher risk of misconfiguration. - **Use a different Hugo theme**: No benefit. Doks provides search, dark mode, sidebar nav, mobile responsiveness, and SEO out of the box. ### Key Findings **Package dependencies** (from complytime-website `package.json`): + - `thulite ^2.6.3` (core framework) - `@thulite/doks-core ^1.8.3` (docs theme) - `@thulite/images ^3.3.1` (image processing) @@ -27,6 +31,7 @@ The complytime-website is a near-identical use case (open source org, Go tool re - `vite ^7.0.6` (dev, preview server) **npm scripts**: + - `dev`: `hugo server --disableFastRender --noHTTPCache` - `build`: `hugo --minify --gc` - `preview`: `vite preview --outDir public` @@ -43,15 +48,19 @@ The complytime-website is a near-identical use case (open source org, Go tool re ## 2. Module Mount Architecture ### Decision + Use `config/_default/module.toml` with explicit mount declarations for all Thulite packages, with `excludeFiles = "home.html"` on the doks-core layouts mount. ### Rationale + Thulite/Doks packages install into `node_modules/` but Hugo needs them in its virtual filesystem. Module mounts bridge this gap. The `home.html` exclusion is mandatory when using a custom homepage layout to prevent conflicts with the Doks default. ### Alternatives Considered + - **Hugo Modules (Go-based)**: Would add Go module complexity and require `go get` commands. The npm-based mount approach is simpler and matches the Thulite ecosystem's intended workflow. ### Mount Categories + 1. **content**: Local `content/` only 2. **data**: doks-core data + local data 3. **layouts**: Local layouts (first priority) + doks-core (excluding home.html) + thulite core + seo + images + inline-svg @@ -65,16 +74,20 @@ Thulite/Doks packages install into `node_modules/` but Hugo needs them in its vi ## 3. Homepage Template Pattern ### Decision + Use a custom `layouts/home.html` with three Hugo template blocks: `{{ define "main" }}`, `{{ define "sidebar-prefooter" }}`, and `{{ define "sidebar-footer" }}`. ### Rationale + These are the standard Doks block names for template inheritance. The `main` block contains the hero section (above the fold), `sidebar-prefooter` contains the feature/project cards, and `sidebar-footer` contains the closing CTA. This pattern is used by complytime-website and integrates cleanly with Doks' base template. ### Alternatives Considered + - **Markdown-only homepage**: Doks does not support a rich homepage layout via Markdown. The custom template is the documented approach. - **Hugo shortcodes**: Would add complexity and fragment the homepage logic across multiple files. ### Content Sections (Unbound Force) + 1. **Hero**: Badge ("Open Source AI Agent Swarm"), title, lead text, CTA buttons (Get Started + View on GitHub) 2. **Features** (4 cards): Agent Personas, Speckit Workflow, Quality-First, Open Source 3. **Projects** (1 card): Gaze -- side effect detection + CRAP scores for Go @@ -85,16 +98,20 @@ These are the standard Doks block names for template inheritance. The `main` blo ## 4. Gaze Project Description (Content Accuracy) ### Decision + Describe Gaze as: a static analysis CLI tool for Go that detects observable side effects in functions (P0-P2 tiers) and computes CRAP scores by combining cyclomatic complexity with test coverage. ### Rationale + This accurately reflects the current state of the Gaze repository. The description must NOT mention GazeCRAP (contract-aware coverage), transitive side effect analysis, or P3-P4 detection, as these are not yet implemented. Per Constitution Principle I (Content Accuracy), only implemented features may be described. ### Alternatives Considered + - **Include planned features with caveats**: Rejected. Constitution explicitly prohibits "Coming Soon" or aspirational content. - **Copy README verbatim**: Rejected. Constitution Principle III requires adapting content for website audience with "why should I care" framing. ### Verified Facts + - Written in Go, requires Go 1.24+ - Two commands: `gaze analyze` (side effects) and `gaze crap` (CRAP scores) - Side effects categorized into P0/P1/P2 tiers (P3/P4 defined but NOT detected) @@ -109,21 +126,25 @@ This accurately reflects the current state of the Gaze repository. The descripti ## 5. CI/CD Workflow ### Decision + Use GitHub Actions with SHA-pinned action references, deploying to GitHub Pages on push to `main`. ### Rationale + This is the standard GitHub Pages deployment pattern. SHA-pinned actions satisfy FR-014 and SC-005 security requirements. ### SHA-Pinned Actions (from complytime-website) -| Action | SHA | Purpose | -|--------|-----|---------| -| `actions/checkout` | `de0fac2e4500dabe0009e67214ff5f5447ce83dd` | Checkout repository | -| `actions/setup-node` | `6044e13b5dc448c55e2357c09f80417699197238` | Install Node.js | -| `peaceiris/actions-hugo` | `75d2e84710de30f6ff7268e08f310b60ef14033f` | Install Hugo | + +| Action | SHA | Purpose | +| ------------------------------- | ------------------------------------------ | ------------------- | +| `actions/checkout` | `de0fac2e4500dabe0009e67214ff5f5447ce83dd` | Checkout repository | +| `actions/setup-node` | `6044e13b5dc448c55e2357c09f80417699197238` | Install Node.js | +| `peaceiris/actions-hugo` | `75d2e84710de30f6ff7268e08f310b60ef14033f` | Install Hugo | | `actions/upload-pages-artifact` | `7b1f4a764d45c48632c6b24a0339c27f5614fb0b` | Upload build output | -| `actions/deploy-pages` | `d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e` | Deploy to Pages | +| `actions/deploy-pages` | `d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e` | Deploy to Pages | ### Alternatives Considered + - **Netlify / Vercel**: Adds external dependency. GitHub Pages is free and integrated with the existing GitHub org. - **Tag-based action references**: Rejected per FR-014 (SHA-pinned required for supply chain security). @@ -132,20 +153,24 @@ This is the standard GitHub Pages deployment pattern. SHA-pinned actions satisfy ## 6. Brand Styling ### Decision + Use electric blue (#3b82f6) as primary and violet (#8b5cf6) as accent, configured via Bootstrap CSS variables in `_variables-custom.scss`. No external fonts. ### Rationale + Colors are specified in FR-007. The complytime-website uses custom Google Fonts (DM Sans, JetBrains Mono) but the Unbound Force spec explicitly prohibits external fonts (FR-013). Doks default fonts will be used instead. ### Differences from complytime-website -| Aspect | ComplyTime | Unbound Force | -|--------|-----------|---------------| -| Primary color | Cyan (#0891b2) | Electric blue (#3b82f6) | -| Accent color | Cyan dark (#06b6d4) | Violet (#818cf8 dark / #8b5cf6 light) | -| Fonts | DM Sans + JetBrains Mono (Google Fonts) | Doks defaults (no external fonts) | -| SCSS scope | Full Tailwind-like color scales | Minimal brand variables only | + +| Aspect | ComplyTime | Unbound Force | +| ------------- | --------------------------------------- | ------------------------------------- | +| Primary color | Cyan (#0891b2) | Electric blue (#3b82f6) | +| Accent color | Cyan dark (#06b6d4) | Violet (#818cf8 dark / #8b5cf6 light) | +| Fonts | DM Sans + JetBrains Mono (Google Fonts) | Doks defaults (no external fonts) | +| SCSS scope | Full Tailwind-like color scales | Minimal brand variables only | ### Alternatives Considered + - **Full Tailwind-style color scales**: Rejected. The Minimal Footprint principle requires simplest implementation. Only the colors needed for `params.toml` and Bootstrap overrides should be defined. --- @@ -153,12 +178,15 @@ Colors are specified in FR-007. The complytime-website uses custom Google Fonts ## 7. Custom Domain Configuration ### Decision + Place a `CNAME` file containing `unboundforce.dev` in `static/`. Domain redirects for `theunbound.dev`, `theunboundforce.dev`, and `thegaze.dev` are handled via DNS registrar URL forwarding (fully out of scope for this repository). ### Rationale + GitHub Pages reads the CNAME file to configure the custom domain. The redirect domains are handled at the DNS level, not in the repository, per the clarification session. ### Alternatives Considered + - **GitHub Pages default URL**: Would work but doesn't establish brand identity. CNAME is trivial to add. - **In-repo redirect logic**: Rejected during clarification. DNS registrar forwarding is simpler and out of scope. @@ -167,9 +195,11 @@ GitHub Pages reads the CNAME file to configure the custom domain. The redirect d ## 8. .gitignore Pattern ### Decision + Adapt the complytime-website `.gitignore`, removing complytime-specific entries (sync-content binary, proposals/, check_workflow_action_shas.py). ### Rationale + Standard Hugo + Node.js ignore patterns. Must exclude `public/`, `resources/_gen/`, `.hugo_build.lock`, `hugo_stats.json`, `node_modules/`, and OS files per FR-003. --- @@ -177,10 +207,13 @@ Standard Hugo + Node.js ignore patterns. Must exclude `public/`, `resources/_gen ## 9. Content Structure (Scaffold Only) ### Decision + Create only `content/_index.md` (homepage frontmatter) in this spec. Documentation content pages (Getting Started, Projects, Team, Contributing) are out of scope -- they are covered by spec 002. ### Rationale + Spec 001 is infrastructure scaffold. The section directories and `_index.md` files for docs sections will be created by spec 002. The homepage needs `content/_index.md` for frontmatter (title, description, lead) consumed by `layouts/home.html`. ### Alternatives Considered + - **Create placeholder section directories**: Rejected. Constitution prohibits placeholder content. Creating empty sections would trigger build warnings and serve no purpose until spec 002 fills them. diff --git a/specs/001-site-scaffold/spec.md b/specs/001-site-scaffold/spec.md index 723463a..db3f09f 100644 --- a/specs/001-site-scaffold/spec.md +++ b/specs/001-site-scaffold/spec.md @@ -13,7 +13,7 @@ - Q: What accessibility compliance level should the site target? → A: WCAG 2.1 AA - Q: How should domain redirects (theunbound.dev, theunboundforce.dev, thegaze.dev) be implemented? → A: DNS registrar forwarding (fully out of scope for this repo) -## User Scenarios & Testing *(mandatory)* +## User Scenarios & Testing _(mandatory)_ ### User Story 1 - Site Builds and Deploys (Priority: P1) @@ -109,7 +109,7 @@ As a visitor, I want the site to have a distinctive visual identity with the Unb - What if the CNAME file conflicts with GitHub Pages settings? The CNAME file in `static/` must match the domain configured in GitHub Pages repo settings. - What if a visitor accesses `http://` (non-HTTPS)? GitHub Pages enforces HTTPS redirect automatically for custom domains. -## Requirements *(mandatory)* +## Requirements _(mandatory)_ ### Functional Requirements @@ -139,7 +139,7 @@ As a visitor, I want the site to have a distinctive visual identity with the Unb - **SCSS Customization**: The two SCSS files that override Doks theme defaults for brand identity. - **CI/CD Workflow**: The GitHub Actions YAML file that automates build and deployment. -## Success Criteria *(mandatory)* +## Success Criteria _(mandatory)_ ### Measurable Outcomes diff --git a/specs/004-gaze-in-practice/plan.md b/specs/004-gaze-in-practice/plan.md index 4b3c486..45d9967 100644 --- a/specs/004-gaze-in-practice/plan.md +++ b/specs/004-gaze-in-practice/plan.md @@ -23,13 +23,13 @@ Both deliverables use real data from `temp/tmp.md` — no fabricated numbers. Th ## Constitution Check -*GATE: Must pass before implementation.* +_GATE: Must pass before implementation._ -| Principle | Status | Evidence | -|-----------|--------|----------| -| I. Content Accuracy | PASS | All data is reproduced verbatim from actual Gaze output (`temp/tmp.md`). No features are fabricated. Warnings about insufficient data are included honestly. Gaze version (v1.2.3) and date (2026-03-02) are identified so content is understood as a point-in-time snapshot. | -| II. Minimal Footprint | PASS | No custom templates, layouts, CSS, or dependencies. One new Markdown file and one section addition to an existing Markdown file. Uses standard Doks table and code block rendering. | -| III. Visitor Clarity | PASS | Blog post explains each section of real output for developers evaluating Gaze. Docs page gets a quick visual preview. Cross-links connect the blog post, docs page, and existing "Why Contract Coverage" article. Blog post is reachable in two clicks from homepage (navbar → Blog → article, or "Latest Articles" → article). | +| Principle | Status | Evidence | +| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| I. Content Accuracy | PASS | All data is reproduced verbatim from actual Gaze output (`temp/tmp.md`). No features are fabricated. Warnings about insufficient data are included honestly. Gaze version (v1.2.3) and date (2026-03-02) are identified so content is understood as a point-in-time snapshot. | +| II. Minimal Footprint | PASS | No custom templates, layouts, CSS, or dependencies. One new Markdown file and one section addition to an existing Markdown file. Uses standard Doks table and code block rendering. | +| III. Visitor Clarity | PASS | Blog post explains each section of real output for developers evaluating Gaze. Docs page gets a quick visual preview. Cross-links connect the blog post, docs page, and existing "Why Contract Coverage" article. Blog post is reachable in two clicks from homepage (navbar → Blog → article, or "Latest Articles" → article). | No violations. No complexity tracking needed. diff --git a/specs/004-gaze-in-practice/tasks.md b/specs/004-gaze-in-practice/tasks.md index 20d088e..d5165e5 100644 --- a/specs/004-gaze-in-practice/tasks.md +++ b/specs/004-gaze-in-practice/tasks.md @@ -74,6 +74,7 @@ ### Implementation Strategy Sequential delivery in priority order: + 1. Complete Phase 1 (blog post) — the primary deliverable 2. Complete Phase 2 (docs update) — quick addition referencing the blog post 3. Complete Phase 3 (verification) — confirm everything works diff --git a/specs/017-gaze-docs-remaining/checklists/requirements.md b/specs/017-gaze-docs-remaining/checklists/requirements.md index feeac63..b860ad4 100644 --- a/specs/017-gaze-docs-remaining/checklists/requirements.md +++ b/specs/017-gaze-docs-remaining/checklists/requirements.md @@ -5,12 +5,14 @@ **Feature**: [spec.md](../spec.md) ## Content Quality + - [x] No implementation details - [x] Focused on user value - [x] Written for non-technical stakeholders - [x] All mandatory sections completed ## Requirement Completeness + - [x] No [NEEDS CLARIFICATION] markers remain - [x] Requirements are testable and unambiguous - [x] Success criteria are measurable @@ -21,6 +23,7 @@ - [x] Dependencies and assumptions identified ## Feature Readiness + - [x] All functional requirements have clear acceptance criteria - [x] User scenarios cover primary flows - [x] Feature meets measurable outcomes diff --git a/specs/018-uf-directory-paths/checklists/requirements.md b/specs/018-uf-directory-paths/checklists/requirements.md index f3ee823..c05e906 100644 --- a/specs/018-uf-directory-paths/checklists/requirements.md +++ b/specs/018-uf-directory-paths/checklists/requirements.md @@ -5,12 +5,14 @@ **Feature**: [spec.md](../spec.md) ## Content Quality + - [x] No implementation details - [x] Focused on user value - [x] Written for non-technical stakeholders - [x] All mandatory sections completed ## Requirement Completeness + - [x] No [NEEDS CLARIFICATION] markers remain - [x] Requirements are testable and unambiguous - [x] Success criteria are measurable @@ -21,6 +23,7 @@ - [x] Dependencies and assumptions identified ## Feature Readiness + - [x] All functional requirements have clear acceptance criteria - [x] User scenarios cover primary flows - [x] Feature meets measurable outcomes diff --git a/specs/019-dewey-karpathy-blog/checklists/requirements.md b/specs/019-dewey-karpathy-blog/checklists/requirements.md index e07dc7a..2c99235 100644 --- a/specs/019-dewey-karpathy-blog/checklists/requirements.md +++ b/specs/019-dewey-karpathy-blog/checklists/requirements.md @@ -5,12 +5,14 @@ **Feature**: [spec.md](../spec.md) ## Content Quality + - [x] No implementation details - [x] Focused on user value - [x] Written for non-technical stakeholders - [x] All mandatory sections completed ## Requirement Completeness + - [x] No [NEEDS CLARIFICATION] markers remain - [x] Requirements are testable and unambiguous - [x] Success criteria are measurable @@ -21,11 +23,13 @@ - [x] Dependencies and assumptions identified ## Feature Readiness + - [x] All functional requirements have clear acceptance criteria - [x] User scenarios cover primary flows - [x] Feature meets measurable outcomes - [x] No implementation details leak into specification ## Notes + - All items pass. Source material verified: VentureBeat article accessible (April 3, 2026), Karpathy X post URL confirmed, Dewey tool count verified via Dewey semantic search (40 tools across 10 categories + new code source type from PR #32). - The issue's "44 MCP tools" claim is outdated — will be verified against current Dewey README during implementation.