diff --git a/CHANGELOG.md b/CHANGELOG.md index 20459d3a..20de5267 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ## [Unreleased] +### Fixed + +- **CONTRIBUTING.md reflowed to clear the reflow-check CI gate (#800, task f4529578).** The markdown prose reflow check (`scripts/reflow_md.py --check`, wired into `make quality`) failed on a hard-wrapped blockquote and a 3-space-indented continuation paragraph in CONTRIBUTING.md. Both were joined to one-sentence-per-line prose with no wording changes, so the check exits 0 ("OK: no hard-wrapped markdown prose in scope"). (Blockquotes are reflow-passthrough — the real failure was the indented continuation at line 31.) This unblocked the competitive-positioning PR (#755) whose CI was red on the reflow step alone. + ## [0.28.0] - 2026-07-29 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 360772fa..9c04d90a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,9 +25,11 @@ The first time you open a pull request, the CLA Assistant bot will comment with 3. Run the full quality gate before opening a PR: ```bash - make quality # ruff format check, ruff check, mypy, pytest --cov-fail-under=80 + make quality # ruff format, ruff check, markdown reflow, mypy, pytest --cov-fail-under=80, xenon, radon ``` +The gate includes a markdown prose reflow check (`scripts/reflow_md.py --check`) that rejects hard-wrapped text in `docs/` and `README.md` — prose must follow a one-sentence-per-line standard. If it fails, run `make reflow-docs` to auto-fix, then re-run `make quality`. See `docs/rag/standards/markdown-reflow-quality-gate.md` for details. + For the frontend (`panel/`): ```bash @@ -45,9 +47,7 @@ Keep commits focused and descriptive. Do not include AI-generated attribution fo `master` is protected by a rule that **every commit must carry a verified signature**. Set this up once and it's automatic from then on; otherwise a maintainer has to bypass the rule to merge your PR. -> This is *cryptographic* signing (`git commit -S`, shown as **Verified** on -> GitHub) — not the `-s` Developer Certificate of Origin *sign-off* trailer. The -> sign-off does **not** satisfy the signature rule. +> This is *cryptographic* signing (`git commit -S`, shown as **Verified** on GitHub) — not the `-s` Developer Certificate of Origin *sign-off* trailer. The sign-off does **not** satisfy the signature rule. The lowest-friction method reuses the SSH key you already use with GitHub: diff --git a/docs/backend/analysis/port-ai-builder-competitive-positioning.md b/docs/backend/analysis/port-ai-builder-competitive-positioning.md new file mode 100644 index 00000000..24dadd30 --- /dev/null +++ b/docs/backend/analysis/port-ai-builder-competitive-positioning.md @@ -0,0 +1,43 @@ +# Competitive positioning: Port AI Builder vs. RoboCo + +**Market signal.** On 2026-07-14 Port launched "Port AI Builder," billed as the industry-first purpose-built vibe coding experience for platform engineering. Its three advertised pillars: human-in-the-loop review and governance, a "Context Lake" for org-specific context, and baked-in domain skills (SRE, DevOps, security, AI governance). Source: https://www.port.io/news/port-ai-builder-announcement + +This doc maps each pillar to the concrete RoboCo backend surface that already serves the same purpose, citing the actual implementation, and states whether RoboCo is equivalent, superior, or genuinely behind on each. + +## 1. Human-in-the-loop review and governance + +**RoboCo surface: the CEO-approval workflow.** + +- RoboCo has a shared CEO-check helper, `require_ceo_role()` (`roboco/api/deps.py:627`), which unifies the orchestrator-router and release-handler gates; the task-approval endpoints below enforce the same CEO-only rule inline. +- The lifecycle spec (`roboco/foundation/policy/lifecycle.py:358-369`) encodes `AWAITING_CEO_APPROVAL -> COMPLETED` (`ceo_approve`) and `AWAITING_CEO_APPROVAL -> NEEDS_REVISION` (`ceo_reject`) as `frozenset({Role.CEO})`-only transitions — no other role can execute either. +- `POST /api/tasks/{id}/ceo-approve` (`roboco/api/routes/tasks.py:2171-2224`) enforces the CEO-only check inline and additionally *requires a substantive note* (`_MIN_NOTES_CHARS`, >= 20 chars) recording why the work is approved for production — an audit trail Port's announcement doesn't detail at this granularity. +- `POST /api/tasks/{id}/approve-and-merge` (`roboco/api/routes/tasks.py:2266-2348`) is the merge-to-master step itself: CEO-only, requires an existing PR (`pr_number`), and calls `GitService.merge_pr_for_task` to squash-merge. +- `TaskService.ceo_approve()` (`roboco/services/task.py:7256`) additionally refuses to approve unless the work session's PR is already `merged` — the human sign-off is structurally the last gate before a task can reach `completed`. +- Beneath the CEO gate, every task already passes an automated PR-review gate (`awaiting_pr_review`, a dedicated `pr_reviewer` role) and a QA pass before it ever reaches the CEO — governance is layered, not a single checkbox. + +**Verdict: functionally equivalent, arguably superior.** RoboCo's CEO gate is a hard, role-checked, single-source-of-truth state-machine transition with a mandatory audit note and a PR-merged precondition, sitting on top of an independent PR-review + QA layer. Port's write-up describes review/governance as a feature of its builder UI; RoboCo's equivalent is enforced at the state machine and API layer, not just presented in a UI. + +## 2. Context Lake for org-specific context + +**RoboCo surface: the in-house RAG/knowledge-base system (`OptimalService`).** + +- `OptimalService` (`roboco/services/optimal.py:158`) is a plugin-based architecture over PostgreSQL + pgvector with a registry of indexes (`PLUGIN_REGISTRY`, `roboco/services/optimal.py:144-155`) covering documentation, journals, errors, standards, decisions, reviews, learnings, playbooks, and CEO vault notes — i.e. org-specific context accumulated from every agent's actual work, not a generic corpus. +- `OptimalService.search()` (`roboco/services/optimal.py:1230`) embeds a query once and runs every index's hybrid (vector + keyword) search concurrently; `OptimalService.query()` (`roboco/services/optimal.py:1339`) aggregates citations across indexes and synthesizes a single answer. +- These are exposed to every agent as MCP tools: `roboco_kb_search` (`roboco/mcp/optimal_server.py:92`, semantic search) and `roboco_ask_mentor` (`roboco/mcp/optimal_server.py:393`, conversational RAG with follow-up context). +- Retrieval isn't only pull-based: `EvidenceRepo.similar_memory()` (`roboco/services/gateway/evidence_repo.py:465`) proactively injects the top-K relevance-floored institutional-memory hits (distilled learnings, approved playbooks, CEO vault notes) into an agent's `context_briefing` at claim time — an agent gets relevant org context pushed to it before it has to think to search. + +**Verdict: functionally equivalent.** RoboCo's RAG stack is the direct analogue of a "Context Lake": org-specific, continuously fed by real agent output (decisions, learnings, journals, reviews), searchable and synthesizable, and additionally push-injected at claim time rather than being pull-only. No gap identified; the branding differs, the capability does not. + +## 3. Domain skills (SRE, DevOps, security, AI governance) baked in + +**RoboCo surface: per-role/team prompts + the architectural-conventions gate.** + +- Every agent's system prompt is composed (`compose_prompt`) from layered role/team prompt files under `agents/prompts/` — e.g. `agents/prompts/roles/developer.md` and the per-team file (`agents/prompts/teams/backend.md`) — which embed the team's tech stack, quality-gate commands, and domain conventions directly into every spawn, not as optional documentation. +- Security/coding/workflow domain guidance is also retrievable on demand via the `roboco_get_standards` MCP tool, backed by `StandardsIndexPlugin` (`roboco/services/optimal_brain/indexes/standards.py`). +- Architectural governance is enforced, not advisory: `.roboco/conventions.yml` (`ROBOCO_CONVENTIONS_ENABLED` - default-off for new projects, on in RoboCo's own deployment, which ships a canonical `.roboco/conventions.yml`) defines which module kinds may hold which definitions; the validator (`roboco/conventions/runner.py:42`) classifies every changed definition and raises `Finding`s. A `block`-level finding (a model in a router, a suppressed lint/type check) hard-refuses both `i_am_done` (`_conventions_gate`, `roboco/services/gateway/choreographer/_impl.py:2498`) and the PR-reviewer's `pr_pass` (`_conventions_guard`, same file, line 2540) — the offending `file:line` plus fix hint is returned in the rejection, and a false positive can only be cleared by committing an explicit, reviewed waiver. + +**Verdict: functionally equivalent, arguably superior on enforcement.** Port advertises domain skills as built-in guidance inside its builder; RoboCo's equivalent is both prompt-embedded guidance (present at every spawn, not opt-in) and a deterministic, code-level enforcement gate that blocks submission on a real violation — a stricter guarantee than "skills baked in" implies for Port. + +## Overall conclusion + +RoboCo has no concrete capability gap versus the Port AI Builder market signal: all three advertised pillars (human-in-the-loop governance, an org-context knowledge base, and baked-in domain-skill enforcement) already exist as real, enforced backend surfaces in RoboCo today, and on two of the three (governance, domain-skill enforcement) RoboCo's mechanism is stricter than what Port's announcement describes — this is a branding/marketing difference, not a functionality difference. diff --git a/docs/backend/qa/ci-reflow-fix-competitive-positioning.md b/docs/backend/qa/ci-reflow-fix-competitive-positioning.md new file mode 100644 index 00000000..07bb67fd --- /dev/null +++ b/docs/backend/qa/ci-reflow-fix-competitive-positioning.md @@ -0,0 +1,40 @@ +# CI Fix: Reflow-Check on Competitive Positioning Doc + +**PR #784 / PR #791 — Resolved** + +## Root Cause + +The Python quality gate's `reflow-check` step was failing on `docs/backend/analysis/port-ai-builder-competitive-positioning.md`. The doc contained hard-wrapped markdown prose (manual line breaks within paragraphs), which the reflow-check rejects — it requires one line per paragraph so that diffs stay clean and the prose reflows naturally in any viewer width. + +The failure was initially suspected to be CI staleness (a prior `sync_branch` rebase was claimed to have resolved it), but `sync_branch` returned `superseded` — the branch was already in sync. The real cause was the hard-wrapped lines in the doc itself, not a stale CI state. + +## Solution Applied + +Reflowed the hard-wrapped prose to one line per paragraph throughout `docs/backend/analysis/port-ai-builder-competitive-positioning.md`. This is a formatting-only change: no content, wording, or citations were modified. The verified wording at line 11 (`require_ceo_role()`) and line 37 (`ROBOCO_CONVENTIONS_ENABLED`) is intact. + +All other quality-gate steps were already clean: ruff format, ruff check, mypy, xenon, vulture, bandit, deptry, alembic, lint-imports, compose-sync, pip-audit. + +## Impact + +- **Scope:** Documentation formatting only (one markdown file) +- **Risk:** None — reflow only changes line wrapping, not content +- **Behavior:** No change to any code, tests, or doc content +- **Verification:** Local `make quality` run confirmed full pass after reflow + +## Pattern + +The reflow-check enforces one-line-per-paragraph in markdown prose files under `docs/`. When authoring or editing markdown docs, write each paragraph as a single long line — let the viewer handle wrapping. Do not insert manual line breaks within a paragraph. + +```markdown +# Correct — one line per paragraph +This is a paragraph. It can be very long, and that is fine. The reflow-check +wants each paragraph on a single line so diffs are clean and the prose +reflows naturally in any viewer width. + +# Wrong — hard-wrapped prose (reflow-check fails) +This is a paragraph. It is manually wrapped +at a fixed column width, which the reflow-check +rejects because it creates noisy diffs. +``` + +If the reflow-check fails on a doc you edited, run `make quality` locally — the failing file and the reflow expectation will be in the output. Join the hard-wrapped lines and re-run the gate. \ No newline at end of file