From bf97da1f9875481248a0d51d696dbe3112c11024 Mon Sep 17 00:00:00 2001 From: "roboco-app[bot]" <302741806+roboco-app[bot]@users.noreply.github.com> Date: Sun, 2 Aug 2026 11:11:39 +0000 Subject: [PATCH] [cdb705da] Backend: competitive-positioning note for Port AI Builder market signal (#755) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [c2d8f8fa] Write Port AI Builder competitive-positioning doc (#722) * [c2d8f8fa] docs(backend): add Port AI Builder competitive-positioning analysis * [c2d8f8fa] docs(backend): fix all wrong file:line citations in Port AI Builder positioning doc --------- Co-authored-by: Backend Developer 1 * [c232e514] Fix PR #755 review findings: wording accuracy + branch staleness (#784) * [4815da95] docs(analysis): fix pr_gate wording findings on CEO-check scope and conventions default (#776) Co-authored-by: Backend Developer 1 * [c0c2ac32] Resolve CI blocker F-397f9453 on PR #784 head (#791) * [c0c2ac32] fix(docs): reflow hard-wrapped prose in competitive-positioning doc to pass quality gate * [c0c2ac32] docs(qa): add CI fix note for reflow-check on competitive positioning doc --------- Co-authored-by: Backend Developer 2 Co-authored-by: Backend Documenter * [26e8731d] Sync branch and resolve pr_gate CI blocker 397f9453 on PR #784 head (#788) * [26e8731d] Document CI staleness pattern in lifecycle artifacts script docstring * [26e8731d] Remove false docstring claiming docs/ is outside CI paths filter The docstring at lines 13-15 claimed docs/ is outside the CI workflow's paths filter, making doc-only commits not trigger CI. This is false — ci.yml lists docs/** at line 44 (push) and line 83 (pull_request). The stale-CI diagnosis built on this false premise is incorrect. Removing the false note per finding F-000d3430. * [26e8731d] docs(contributing): list markdown reflow check in make quality gate description CONTRIBUTING.md's make quality comment listed only 4 checks (ruff format, ruff check, mypy, pytest) but the Makefile quality target runs 8+ including the markdown prose reflow check (scripts/reflow_md.py --check). That omission directly contributed to the CI blocker this task investigated — a contributor reading the old comment would not expect the reflow gate. Added the reflow check to the comment list and a note pointing to make reflow-docs as the auto-fix and docs/rag/standards/markdown-reflow-quality-gate.md for the standard. --------- Co-authored-by: Backend Developer 2 Co-authored-by: Backend Documenter --------- Co-authored-by: roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com> Co-authored-by: Backend Developer 1 Co-authored-by: Backend Developer 2 Co-authored-by: Backend Documenter * [f4529578] Reflow CONTRIBUTING.md blockquote to clear reflow-check CI failure on PR #755 (#800) * [f4529578] reflow(contributing): join 3-line blockquote and strip line 31 indent to clear reflow-check * [f4529578] docs(changelog): note CONTRIBUTING.md reflow fix that cleared reflow-check CI gate * [f4529578] docs(changelog): clarify reflow fix unblocks competitive-positioning PR #755 * [f4529578] docs(changelog): add reflow-passthrough detail to CONTRIBUTING.md fix note * [f4529578] docs(changelog): add task ID reference to CONTRIBUTING.md reflow fix entry * [f4529578] docs(changelog): add exact reflow-check exit output to CONTRIBUTING.md fix entry * [12b3bce9] fix(contributing): join blockquote and remove indent to clear reflow-check CI failure (#799) Co-authored-by: Backend Developer 1 --------- Co-authored-by: Backend Developer 1 Co-authored-by: Backend Documenter Co-authored-by: roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com> --------- Co-authored-by: roboco-app[bot] <302741806+roboco-app[bot]@users.noreply.github.com> Co-authored-by: Backend Developer 1 Co-authored-by: Backend Developer 2 Co-authored-by: Backend Documenter --- CHANGELOG.md | 4 ++ CONTRIBUTING.md | 8 ++-- ...port-ai-builder-competitive-positioning.md | 43 +++++++++++++++++++ .../ci-reflow-fix-competitive-positioning.md | 40 +++++++++++++++++ 4 files changed, 91 insertions(+), 4 deletions(-) create mode 100644 docs/backend/analysis/port-ai-builder-competitive-positioning.md create mode 100644 docs/backend/qa/ci-reflow-fix-competitive-positioning.md 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