Changelog¶
All notable changes to Primr will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]¶
Changed¶
- A skill-pack role plan can record which skill names answer a strategy opportunity. The link stores the workflow, intervention class, and evidence note. A hiring advertisement, a DNS or recon signal, or another weak basis is stored as a refusal. A plan with no strategy context says that no opportunity is linked. This does not add a model call, and it does not author the skill.
- The AI Strategy prompt contract is 2.3.0. Each prioritized initiative names the smallest useful intervention: a reusable skill, a deterministic workflow, a bounded agent, or a human-led, defer, or no-AI alternative. Allowed actions and stopping conditions are required only for a bounded agent. A job advertisement, a DNS or recon signal, or a public complaint is too weak to justify a skill or an agent. Unknown baselines, owners, and permissions stay unknown.
[1.39.36] - 2026-11-16¶
Fixed¶
primr doctorlaunches Chromium with the same check preflight uses. A missing browser fails doctor and namesplaywright install chromium.primr doctor --fixstill offers to install it. A native probe crash stays a warning so doctor itself keeps running.- A missing model key now suggests only Gemini, xAI, and OpenRouter, the
providers that can run a full report. OpenAI and Anthropic stay available
for estimates and evals.
primr doctormarks those two rowsestimate/eval only. primr doctorprobes web search under Connectivity. The default engine is no longer labeled DuckDuckGo. A DNS failure saysno network or DNS; search checks skippedand does not send the user toprimr doctor --fix.- Cloud cancellation grace is measured from the cancel request. A repeated
cancel does not restart that clock. A stored job with no cancel-request
time gets one grace period from the first reconciliation that sees it.
cancellation_timeoutmeans the control plane stopped waiting. It does not prove the provider process has exited. - A failed queue accept no longer leaves an approved job stuck in
QUEUED. The same idempotency key retries the accept once. A request that already reached the queue is not submitted again, and a new key still is.
Changed¶
primr --execsrequests optional leadership context. It stays off unless the flag is set and does not change the Strategic Overview. This slice renders a brief from sources already in hand, for at most three roles. It does not search the web, call a model, or add model spend.- The Google GenAI SDK floor is now 3.3.0. Clients keep API version
v1betabecause deep research uses the Agents API, which is not inv1. The request timeout stays finite. - The optional A2A extra now installs SDK 1
(
a2a-sdk[http-server]>=1.3,<2). The server speaks protocol 1.0 and still accepts 0.3 JSON-RPC methods on the same endpoint. The agent card is served at/.well-known/agent-card.json, and/.well-known/agent.jsonstays as an alias. A task stream opens with a Task before its first status event. - The optional Anthropic extra now installs SDK 2 (
anthropic>=2,<3). Messages requests omittemperature,top_p, andtop_k. API version 2026-10-21 rejects those parameters on every model, so the call samples at the API default. The provider argument stays on the shared interface. - GitHub Actions runs finish even when a newer commit is pushed on the same pull request. Release publishing and the docs site still run one at a time, and a waiting run stays queued instead of being replaced.
[1.39.35] - 2026-11-16¶
Security¶
- Raise the transitive
soupsievefloor to 4.0.0 and thednspythonfloor to 2.9.2.soupsievebefore 4.0.0 can stall on crafted selectors (CVE-2026-126190, CVE-2026-126191, CVE-2026-126192, CVE-2026-126193).dnspythonbefore 2.9.2 can exhaust memory while parsing a malicious WKS record (CVE-2026-128089). Both are reached through existing dependencies. The constraints cover locked source and container installs.soupsieve4.0.0 requires Python >=3.11.5, so the published floor moves to that patch. Python 3.11 through 3.15 stay supported; current 3.11 installers are past 3.11.4. - Raise the transitive
pyasn1floor to 0.6.5. Versions before 0.6.5 spend quadratic CPU while decoding crafted ASN.1 (CVE-2026-119194, CVE-2026-119195, CVE-2026-119196, CVE-2026-119197). The package is reached throughpyasn1-modules; the constraint covers locked source and container installs, and pip consumers resolve their own transitive versions. - Reviewed dependency updates: openai 3.41.0 (major: HTTPX2 replaces httpx as the SDK's default client; Primr's bounded transport still constructs it with redirects disabled and retries owned by Primr), azure-identity 1.27.0, boto3 and botocore 1.43.122, curl-cffi 0.17.0, msgpack 1.2.4, patchright 1.64.3, pytest-asyncio 1.4.1, and hypothesis 6.170.14. The runtime container export is regenerated to match the lock.
- Reviewed dependency updates: google-genai 2.34.0, opentelemetry-api 1.45.2,
pydantic 2.14.2, pydantic-settings 2.16.2, pytest 9.2.0, mypy 2.4.1, boto3
and botocore 1.43.123, azure-storage-blob 12.31.1, azure-keyvault-secrets
4.12.0, and cyclonedx-bom 7.6.0. pydantic 2.14.2 is now a direct floor
(GHSA-qpmf-fgh3-ff25, GHSA-3r8g-cqwr-jr29). Both container exports are
regenerated to match the lock. GitHub Actions
setup-uvmoves to 10.3.3. The uv tool pin stays 0.13.5. - Cap the optional Anthropic extra at
anthropic>=0.109.1,<1. SDK 1.0 removedtemperaturefrommessages.create, and SDK 2.0 sends API version 2026-10-21, which rejects that parameter on every model. Older Claude tiers still receive temperature as a top-level argument. Install hints point atprimr[anthropic]so a bare install does not select SDK 2.x.
Changed¶
- CI installs CPython 3.15.2 into the job workspace. The pinned uv 0.13.5
manifest stops at 3.15.1, so the 3.15 jobs pass a checked-in download
manifest to
uv python install. The interpreter is not taken from the runner image, and the uv pin stays 0.13.5. - Disclosed and reported figures stay as stated. The composed overview, the fast-mode system prompt, the fast trust polish, and the contradiction edit use a range only for a genuine estimate and say how it was made. The company-brief skill, which agents copy when they cannot run the pipeline, follows the same rule and the same analytical voice.
- Living roadmap text that still called the current hybrid default Grok 4.3 now names Grok 4.7 with Gemini 3.5 Flash-Lite writing. The continuous-reasoning pilot numbers stay attributed to the Grok 4.3 run that produced them. The design principle now matches the shipped Overview voice: label a load-bearing fact, label a non-fact Hypothesis, and do not hedge every sentence.
- A 2026-11-02 catalog recheck found no newer generally available flagship and
no price change on the default routes. xAI still lists Grok 4.7 at $2/$6 per
million tokens ($0.50 cached; $4/$12 at or above 200k).
grok-4.20-non-reasoningremains the alias of the dated non-reasoning model. Gemini 4 Argon still steps up on 2026-12-01, and Gemini 3.8 Flash on 2027-01-01. - Strategic Overview sections are longer and build on each other. Section word floors rise from 1,200 and 800 to 1,500 and 1,000 words (about 25,500 words, or 50+ pages, across the default 23 sections), with output limits raised to match. Writers are told to refer back to an earlier theme in a clause and spend their words on what is new through their section's lens, never to shorten a section to avoid overlap.
- Financial sections anchor on the most recent disclosed figures, with period and source, and show the numerator and denominator behind any ratio. Ranges are reserved for genuine estimates with a stated method.
- Confidence labels apply to load-bearing factual claims. Strategic analysis is written directly, without a hedge on every sentence; the rules that required "appears to" phrasing and rewriting every risk as a scenario are replaced by an analytical-voice rule.
- Engagement sections ask for budget signals instead of inviting invented dollar ranges, and use a relative time horizon instead of hardcoded years.
- The default estimate rises from about $1.24 to about $1.26 ($1.08 without the AI Strategy) to cover the longer sections. Current tables match that plan: two-platform about $1.45, xAI-only about $5.99 ($5.24 without the AI Strategy), MAX about $10.05 ($8.65 without it), and OpenRouter about $0.68. Dated routing snapshots stay as history.
- Operator and skill guidance describe the Strategic Overview as direct analysis with cited sources. The length guidepost is about 25,500 words. The roadmap's current Standard mode names Grok 4.7 reasoning and Gemini 3.5 Flash-Lite writing.
Fixed¶
- Retired Grok 4.1 Fast quotes on or after 2026-05-15 use grok-4.7 rates
from the xAI pricing page checked 2026-11-14 ($2/$0.50 cached/$6 below
200k prompt tokens, $4/$1 cached/$12 at or above 200k). Earlier dates
keep the $0.20/$0.50 list price. Opt-in OpenAI icon generation requests
gpt-image-2.6-flare. From 2026-12-01, quotes forgemini-2.5-proandgemini-2.5-flashfollowgemini-3.8-flashandgemini-3.5-flash-lite. Live defaults now use only current model ids: every xAI tier usesgrok-4.7, Gemini Pro usesgemini-4-carbon, Flash usesgemini-3.8-flash, Flash-Lite usesgemini-3.5-flash-lite, OpenAI usesgpt-6.1-sol,gpt-6.1-terra,gpt-6-luna, orgpt-6-astra, and Anthropic usesclaude-fable-5-2,claude-opus-5-5,claude-sonnet-5-5, orclaude-haiku-5-5. Superseded ids stay registered for historical quotes.gemini-2.5-proandgemini-2.5-flashare deprecated and shut down on 2026-12-01. Until that date an explicit selection still works and warns. On that date it is refused in favor ofgemini-3.8-flashandgemini-3.5-flash-lite. Quotes before the shutdown keep the stored 2.5 rates, and quotes on or after it use the successor rates. Directgemini-2.5-flash-liteis not deprecated and remains available. The OpenRouter row for that id is not selectable. Deprecation notes were rechecked against the Gemini deprecations page on 2026-11-16. Other superseded ids are not selectable. - Current architecture, run-mode, onboarding, and queue notes name
gemini-4-carbonas the Pro default andgrok-4.7for every xAI tier. Gemini 4 Argon stays registered. The 2026-10-28 flagship table stays as history. - The Strategic Overview voice now covers the fast-mode system prompt, the composed overview persona, and the section briefs. Those paths no longer tell the writer to treat every claim as a hypothesis or to hedge wins, losses, and executive perspectives. A claim that is not a fact stays a labeled Hypothesis. Strategy prompts are unchanged.
- Repository, package metadata, installer, support, agent-plugin, and runtime
identity links now point to
pueo-labs/primrafter the repository transfer. The documentation site useshttps://pueo-labs.github.io/primr/; GitHub does not redirect the previous Pages URL. Package and plugin names, versions, author attribution, and historical release records are unchanged. - Claude Code setup now loads the checked-in plugin directory instead of advertising a marketplace catalog that the repository does not publish.
- The composed Strategic Overview prompt and the deep-research section template now use the analytical voice. Shared rules that required "appears to" phrasing, "worth exploring" as the confident line, and rewriting every risk as a scenario no longer ride along. The section template deepens a recurring theme instead of cutting it.
- Reports no longer gain a stray "(Reported)" line on sections that had no parenthesized label.
- A section's own "What to validate" question is kept when the writer emits it as a heading, bullet, or bold label, instead of being replaced by a generic default line.
[1.39.34] - 2026-10-29¶
Changed¶
- The roadmap now follows Primr's outputs. v1.40 deepens the Strategic Overview (typically 50 or more pages, every section adding depth); v1.41 completes the strategy library, with AI Strategy as the default and every listed strategy role-agnostic and at least 30 pages; v1.42 ties skill packs to the company's roles and strategy; v1.43 brings Primr Zero to the same quality with no API spend. Backend freedom, the agent control plane, and run history follow, and the run ledger becomes an optional internal aid. The product contract states that Primr is deep consultant preparation for any role, not a financial analyst's report or a fact lookup, and that fixing repetition means deepening sections, never shortening reports.
- Model defaults and prices were rechecked against the xAI, Gemini, OpenAI, Claude, and OpenRouter catalogs on 2026-10-29. No newer generally available model or price change applies; the default full run (Strategic Overview plus AI Strategy) still estimates $1.24.
Added¶
- OpenRouter routes for Kimi K3.1 Pro, Meta Muse Spark 1.3, and Mistral Large 4, three leading models from OpenRouter's benchmark leaderboard that Primr did not yet register, priced from OpenRouter's endpoints API on 2026-10-29.
Fixed¶
- The OpenRouter GLM 5.3 Flash route could not run: its registered rate, which Primr also sends as the request price ceiling, was below every provider serving the model. It now uses Z.AI's first-party rate.
[1.39.33] - 2026-10-28¶
Changed¶
- The README, product contract, agent guide, operator guide, and package description now state plainly that Primr is a research and consulting-prep tool whose reports mix cited facts from public sources with reasoned strategy that companies rarely publish. It is not only a fact checker: quality is judged by research grounding, insight, specificity, and usefulness, not by how much can be verified.
[1.39.32] - 2026-10-28¶
Changed¶
- The v1.40 card now improves the Strategic Overview, AI Strategy, and skill pack directly instead of waiting on people adjudicating facts. Strategy analysis is reasoned judgment, so changes are confirmed by reading before and after outputs side by side; model judges are a second opinion and claim-label checks remain diagnostics. The product contract, roadmap, next steps, and evaluation plan record the change.
[1.39.31] - 2026-10-28¶
Changed¶
- Default models now track each provider's current flagship, checked against the xAI, Gemini, OpenAI, and Claude catalogs and the OpenRouter models API on 2026-10-28. Grok 4.7 reasons in every tier (MAX also writes with it); Gemini 3.8 Flash and Gemini 4 Argon replace the Gemini 3 Flash and 3.1 Pro previews; Gemini writing uses 3.5 Flash-Lite; OpenAI-only runs use GPT-6 Luna and the new GPT-6.1 Terra; Anthropic-only runs use Claude Haiku 5.5 and Sonnet 5.5; OpenRouter routes use Gemini 3.5 Flash-Lite, GPT-6 Luna, and DeepSeek V4.1 Flash; the LLM judge default is Grok 4.7. Fallback chains follow the same models. This is an owner decision, not a measured quality promotion.
- The default xAI plus Gemini estimate rises from about $0.89 to about $1.24
with the AI Strategy (base report $0.76 to $1.05). OpenRouter defaults fall
from about $1.07 to $0.67 and Anthropic-only from $4.71 to $3.20. Always
use
--dry-runfor the live quote.
Added¶
- GPT-6.1 Terra is registered directly and on OpenRouter with its standard, long-context, cached, and cache-write rates.
- Estimates disclose scheduled provider price changes. Gemini 4 Argon rises to $4/$20 on 2026-12-01 and Gemini 3.8 Flash to $1.50/$7.50 on 2027-01-01, so a quote approved before those dates names the new rates.
- A routing test fails when any provider key combination sends a default role to a model outside the current flagship set.
Fixed¶
- The OpenRouter
openai/gpt-4.1-miniroute is unavailable ahead of OpenAI's 2027-01-14 shutdown and namesopenai/gpt-6-luna; Grok 4.1 Fast records its 2026-05-15 retirement. Both stay priced for historical accounting. - Usage summaries, QA model metadata, and capability-routing price hints use date-effective rates instead of base rates, and QA metadata now describes the configured models instead of Gemini 3 Flash and 3 Pro.
- The CLI help cost guidepost is now checked against the live estimator.
[1.39.30] - 2026-10-28¶
Added¶
- The evaluator validation harness gains an
authority_without_supportvariant: the supporting span is removed and a strong trust cue is prefixed, so a judge that accepts it is scoring source authority instead of claim support. Cases may supply anauthority_cue; abstaining counts as detection by default. The generator version is now 3, so earlier frozen sets record which rules built them.
Fixed¶
- A single-section writer response that opens with prose before a
differently titled
##heading keeps that heading as a###subsection instead of losing its title.
[1.39.29] - 2026-10-28¶
Changed¶
AGENTS.mdis now the single source of agent guidance: the root file holds the development contract formerly inCLAUDE.md, andCLAUDE.mdis exactly@AGENTS.md, the import Claude Code needs to load it. The operate-primr guide moved toclients/primr-operator.md; copy it into a workspace asAGENTS.md. Its reference links are now absolute. Theprimr://contextMCP resource readsAGENTS.mdand reportscontext_map_path: "AGENTS.md"(#264).
[1.39.28] - 2026-10-27¶
Changed¶
- Client-facing Word reports open with the title and the Executive Summary.
Recorded collection counts move from beneath the title to one muted closing
Collection notein every Word path (Markdown conversion, premium builder, and text conversion), with unchanged wording and meaning. Terminal coverage output is unchanged. This supersedes only the under-title placement from #229/#236 (#263).
Fixed¶
- Writer section envelopes are parsed at the section-parsing boundary instead of
leaking as report prose. An envelope missing its body tags, or its closing
section tag after a closed body, is repaired. A truncated envelope keeps its
text, earns one retry, and warns the operator. An envelope without a title,
or with nested structural tags, is kept verbatim, the coherence pass is
skipped so no model rewrite guesses a repair, and the polished DOCX is
withheld with the Markdown kept for review. Only structural envelope tags
outside code count, so prose or code that mentions an HTML
<title>element does not block a report. Repeated title lines and headings around an envelope no longer duplicate the section title (#263). - Single-section writer responses no longer drop later
##blocks silently; they are kept as###subsections. A## Referencesblock is moved last, so the existing references policy removes only it.
[1.39.27] - 2026-10-27¶
Added¶
primr doctorwarns when OpenAI's free model list reports a past or scheduledshutdown_datethat the model registry does not record, or a different date than it records. The check runs only whenOPENAI_API_KEYis set, passes the SSRF guard, is bounded to 10 seconds, makes no generation call, and never changes routing (#258). The CLI smoke test now blanks provider keys so the default suite stays offline.
[1.39.26] - 2026-10-27¶
Added¶
- Add a library-only evaluator validation harness for the v1.40 quality card. Adjudicated clean cases yield controlled variants for nine error categories. Items, pre-registered tolerances, and the generator version are frozen under one digest. Judges run blind across seeded passes; recall, false alarms, abstention, failures, repeat flips, shared errors, and agreement are scored with Wilson intervals. Disagreements, flips, and seeded samples of unanimous approvals and rejections are queued for human review. A decision needs an all-human-adjudicated set, two judges, two passes, and complete human review. It never arms a gate. No judge has been measured with it yet.
Changed¶
- Take the reviewed ddgs, hypothesis, mkdocs-material, and starlette updates proposed in #259 and regenerate both container requirement exports.
[1.39.25] - 2026-10-27¶
Security¶
- Constrain locked and container installs to filelock 4.2.1 or newer (CVE-2026-112907, CVE-2026-112913, CVE-2026-112940), virtualenv 21.14.13 or newer (CVE-2026-115586), and dnspython 2.9.0 or newer (CVE-2026-114605). These are transitive packages reached through tldextract, virtualenv, pip-audit, and recon-tool; pip consumers resolve their own versions.
- Take the reviewed Python, setuptools, and GitHub Actions updates proposed in #254, #255, and #256, and regenerate both container requirement exports.
Fixed¶
- Route OpenAI-only reasoning to GPT-5.6 Terra, OpenAI's named substitute for
o4-mini, which shut down on 2026-10-23. o4-mini remains priced for historical
accounting and now reports its shutdown and replacement before egress.
Replace the
o4mini-flashliteeval slot withterra-flashlite; its cost is a planning figure, not a measurement. - Request
gpt-image-2.5-flarefor opt-in OpenAI icon generation after the gpt-image-1 shutdown, andgrok-imagine-image-2.0at explicitmediumquality for xAI before the 2026-11-02 retirement ofgrok-imagine-image-quality. Medium keeps the retired slug's intent instead of the provider's low-quality redirect. Image model IDs now live inconfig/models.py. - Record the announced 2027-04-01 shutdown of gpt-5.4-nano with gpt-6-luna as
its replacement. The OpenAI-only writing default is unchanged until then.
OpenRouter's
openai/gpt-4.1-miniroute is unchanged because the gateway still lists it.
Changed¶
- Add start-tidy and stop-tidy contributor rules to
CLAUDE.md(#252).
[1.39.24] - 2026-10-22¶
Security¶
- Update UV to 0.13.5, pip to 26.2.2 or newer, virtualenv's embedded installer floor to 21.14.12, and the SHA-pinned publishing action to 1.14.3 with sigstore 4.5.1. Hash-bootstrap container installers before dependency downloads and rebuild CI containers without cached layers. Separate installation-tool trust stores from the existing application certifi fix. Guard the convenience installers and self-update path against affected UV or pipx shared installers before package downloads.
Added¶
- Register current GPT-6/6.1, Claude 5.5/Fable 5.1, Grok 4.7, curated gateway, Bedrock Nova 2/Claude, and local Qwen 3.8/Gemma 4 candidates with dated official pricing. Keep evaluated routing defaults unchanged. Allow an explicit Foundry Responses API setting for compatible current deployments.
Fixed¶
- Correct direct and gateway standard/cache prices, context tiers and retired route availability. Preserve original Gemini alias accounting dates on a catalog recheck. Use documented conservative ceilings for time-varying gateway rates and retain native billing as authoritative.
- Apply the prompt tier to recorded single-call costs, include all declared tiers in gateway request ceilings, reject non-finite deployment prices, and omit unsupported Claude sampling controls on Messages and Bedrock Converse. Reject attempts to disable always-on Claude thinking before SDK calls.
- Prevent automatic paid cache writes on current direct OpenAI Responses calls. Include published write-price ceilings in conservative quotes, retain exact provider billing when available, and apply the newer Claude tokenizer margin across verified direct and gateway model families.
[1.39.23] - 2026-10-22¶
Security¶
- Require OpenTelemetry API 1.45.1 or newer for bounded inbound tracestate parsing, including published wheel installs. Update the locked development environment tool to virtualenv 21.14.9 or newer for activation and POSIX launcher quoting fixes. Regenerate the hashed container dependency exports.
Fixed¶
- Compare local judges against the exact sampled claims and saved cloud verdicts, without rereading or rejudging reports. Reject incomplete local judge plans before provider calls, exclude changed report or sidecar artifacts from agreement counts, and continue the batch after individual cloud, local, or decoding failures. Write calibration sidecars atomically.
- Separate bounded browser dependency setup from the native CI test and use Ubuntu's HTTPS archive for runner package downloads. Preserve the native test deadline and Chromium sandbox checks when archive mirrors are slow.
[1.39.22] - 2026-10-20¶
Security¶
- Bound wire and decoded HTTP bodies before Requests, HTTPX, or curl can buffer them, including redirect and status-retry responses. Keep retries inside the request budget and negotiate only bounded content decoders.
- Enforce sitemap document and expansion limits, parse XML incrementally, and share attempt, content, and elapsed-work budgets across roots and indexes.
- Replace repeated HTML subtree scoring with shared linear metrics and reject excessive DOM depth or node counts before extraction passes.
- Run local PDF extraction in an owned child with OS memory limits, a wall timeout, and page/text budgets. Retain stricter inherited memory/CPU limits. Discard native diagnostics, exclude provider credentials, and visibly mark text truncated at an extraction budget.
- Explicitly enable the documented Chromium sandbox default in Playwright and Patchright launch options. Keep the existing operator opt-out for hosts that cannot support sandboxing; never downgrade automatically after a launch error.
[1.39.21] - 2026-10-20¶
Security¶
- Require report scope and current-job ownership before remote QA, strategy, and skill-pack tools reuse local artifacts. Confine A2A QA inputs to the same roots as MCP and process bounded stable snapshots. Check linked paths before resolution, protect nested evidence/JD/plan reads, and isolate remote output destinations. Trusted local artifact reuse remains available.
- Bound fallback HTTP transfers and decoded bodies before buffering, including gzip and deflate expansion. Close redirect bodies unread and check the fetch deadline between raw reads. Apply the image byte cap at the network seam.
- Sanitize URL-derived raw-scrape filenames for Windows path, drive, and stream syntax and keep writes beneath the run's raw-scrape directory.
Fixed¶
- Serialize QA's actual component scores, preserve report identity during snapshotting, and run synchronous QA work outside the controller event loop.
- Canonicalize retained artifact paths through the same validator as caller inputs so trusted macOS temporary-directory aliases preserve ownership.
- Keep cloud job company names positional, reject reserved commands, validate vendor options, and pass supported public research modes to the CLI. Resolve local runner output through the parsed artifact store, including escaped file URIs, and align MCP file roots with configured report/working directories.
[1.39.20] - 2026-10-20¶
Security¶
-
Require Pillow 13.0.0 or newer across package and container installs for the October decoder/encoder advisories. Validate remote icon byte and pixel limits before decoding PNG or JPEG; reject malformed and unsupported images through the existing local-icon fallback. Read Gemini inline image bytes using the current SDK API without decoding outside that shared boundary.
-
Require certifi 2026.10.19 or newer in published package metadata and the locked source/container environments. This removes the affected emSign root from certifi's bundle (GHSA-6q48-6c7w-9gw2) without changing custom CA or TLS verification behavior. Rebuild container images to consume the refreshed bundle.
-
Require MCP SDK 2.2.0 or newer and update the locked SDK and container export. Legacy HTTP sessions now use upstream capacity limits, idle expiry, and closed-session reclamation, addressing CVE-2026-59951 while preserving modern request-scoped and legacy initialized clients.
Fixed¶
-
Validate background research IDs before saving or polling a job, and keep experimental job creation explicitly non-streaming with current Google SDKs.
-
Reject authored Python replacement fields across maintained interpreters, including newer f-string syntax that Python 3.11 cannot parse.
-
Preserve claim evidence labels in Word reports without adding risk dots or assigning whole-report confidence from citation totals. Compatibility formatters accept only explicit Confirmed, Reported, Estimated, and Hypothesis labels. Recommendation priorities use words in navy, and muted text uses contrast-tested #6B6B6B.
-
Remove research-stage back imports through typed trust and strategy callbacks and one canonical owner for the existing legacy section pipeline. Public compatibility exports remain lazy; scrape gates, progress, explicit folders, and existing callback seams are retained. The first-party import graph is now acyclic and cannot grow a new cycle without failing CI.
-
Return a structured error if a hypothesis disappears while applying an update. Complete ranked-link comparisons without changing stable tie ordering or record equality, and accept custom awaitables at the sync boundary.
-
Remove unused transport publication state, duplicate scrape-cache allocation, unused telemetry imports, and unused generic declarations. MCP cost-cap enforcement remains enabled by default on every transport.
-
Keep keyless startup and estimate requests free of setup prompts. Show a short home screen with the prep path first, and a static ANSI wordmark only at home or on explicit banner requests.
- Report each provider once in compact doctor output. Local readiness now comes from the existing endpoint probe; an optional authentication placeholder no longer makes Ollama configured or eligible for automatic key validation.
-
Send progress, warnings, and failures to stderr while preserving result and JSON output on stdout. Mask progress text before truncation and formatting; wrap doctor details and grouped key states for narrow terminals.
-
Reject retired direct Gemini Pro and image previews during selection and before requests, with the provider's replacement named. Keep historical model identities and costs, active Flash Preview, and prior-user-only Gemini 2.5 routes. Direct Google and OpenRouter retirement policies remain separate.
-
Remote Gemini icons use current Nano Banana 2.1, with an explicit
AI_IMAGE_MODELoverride for supported Gemini image models. -
Frozen calibration evidence binds only to its recorded URL. Case-sensitive paths, query values, and unrecorded trailing-slash aliases cannot substitute another resource's text. Exact empty captures still prevent live fetching.
- Unusable prep bundles retain their specific recovery instruction and no longer end with a contradictory host-synthesis handoff.
Changed¶
-
Update the Ruff lock to the latest reviewed patch in the supported 0.15 line, preserving the existing compatibility cap and source formatting.
-
Refresh the reviewed runtime, build, test, and typing dependencies within the existing package bounds, including Google Gen AI, HTTP/ASGI clients, cloud SDKs, and mypy. Regenerate the hash-locked container exports. Python update proposals now preserve manifest bounds; the intentional Ruff cap remains.
-
Refresh pinned artifact upload/download, CodeQL, Pages deployment, build provenance, and PyPI publishing actions to reviewed compatible releases. Preserve immutable-tag checks, trusted publishing, and existing permissions.
-
Cancel superseded PR validation while retaining independent CI and CodeQL results for every main commit and scheduled scan.
-
End prep and provider-backed research with one factual collection signature, and repeat those recorded counts beneath the Word title. Missing metadata stays unknown, archived and public captures stay separate from current first-party pages, and only identity-linked hiring postings count. The terminal wraps at its actual width; unusable bundles remain visibly incomplete. JSON is unchanged.
-
primr render --evidence-bundle PATHverifies the explicit prep bundle before adding its collection counts. Verified older bundles retain support through their bound captured text. Standalone rendering never guesses provenance. -
Give evaluation profile contracts, declarative candidates, and registration their own configuration boundaries. Routing and the legacy Gemini helper use the shared provider cache without importing the evaluation runner or each other. Preserve the public evaluation imports and per-run recipe overrides.
-
Remove the fallback-source import cycle by giving recovery adapters a shared typed result and HTTP callback contract. The fan-out injects its SSRF-safe transport explicitly; standalone adapters use the same canonical HTTP seam.
-
Enable bounded, grouped dependency-update proposals for Python, Actions, and container images while retaining maintainer review, commit authorship, and all security gates. Surface supported versions and private disclosure details in the root security policy. Allow a manual Scorecard refresh after CI settles, and use the current pinned Scorecard action and its migrated public endpoints.
-
Register Gemini 4 Argon with synchronous output limits, current pricing, and the December 1 price change. Report reasoning and writing defaults remain evaluation-gated. The current-model view excludes superseded aliases and restricted legacy models while preserving their accounting records.
- Price the currently verified Gemini aliases through their canonical models from the verification date, including scheduled rates and caching. Preserve the requested route identity and earlier dated catalog prices; no unannounced alias cutover date is invented. Telemetry uses the same dated pricing facade.
-
Move direct Gemini catalog data into its owning module so the registry and selection facade do not grow into larger files.
-
Support maintained Python 3.11 through 3.15 and use stable 3.15 for development, release builds, containers, and primary platform CI. Refresh pinned Actions and the native dependencies needed for 3.15 wheels. Keep the isolated, hash-pinned Atheris engine on its supported 3.13 interpreter.
- Restore sync browser collection on 3.15 with verified greenlet 3.5.6 or newer, retaining fail-closed behavior for unverified runtimes. Skill-pack cleanup uses the error handler supported across the full maintained Python matrix.
- Verify native offline browser rendering separately from unit tests on the primary platform lanes. Type-check both the maintained floor and newest stable runtime, and refresh audit tooling for Python 3.15 compatibility.
-
Require the current DDGS search client, removing the old Brotli dependency that required a compiler when installing or building containers on Python 3.15.
-
Label-calibration gate. The candidate
PRIMR_EVAL_MIN_CONFIRMED_TRACEABILITYvalue is now a report-clustered Wilson lower bound at 95 percent confidence, recorded asbound_method,confidence, andbound. Calibration can judge frozenscraped_content.txtcaptures, sends the judge claim text with the confidence label removed, draws a seeded sample, and records each judge verdict. An explicit abstain does not count as untraceable. A human-confirmedhonestly_empty_confirmedreport with no Confirmed claims does not block the floor. The operator sets that boolean on the pack selection report; Primr does not infer it.
[1.39.19] - 2026-10-13¶
Fixed¶
- Reject published OpenRouter Gemini 2.5 expirations from October 20, 2026 UTC in role selection and before model requests, preserving catalog indices and historical cost accounting. Replacements require explicit selection and a new estimate. Direct Gemini Developer API records retain their distinct prior-user access restriction and have no announced shutdown date.
- The developer pilot judge uses the configured reasoning model, including
AI_REASONING_MODEL, instead of a hardcoded Gemini 2.5 Pro. - Direct Gemini utility and reasoning routes honor
AI_FAST_MODELandAI_REASONING_MODELbeneath their existing role-specific overrides. OpenRouter extension bodies cannot substitute a different model or a model fallback list after retirement and pricing checks.
[1.39.18] - 2026-10-12¶
Security¶
-
Point private vulnerability reports to GitHub's reporting form and update the supported security-fix series to 1.39.x.
-
Updated the locked HTTP, TLS, JWT, HTML-selector, and development-environment dependencies to patched releases. Source and container resolution now enforce transitive security constraints, and the directly used urllib3 client has a published minimum of 2.8.0. Regenerated the hash-locked container exports.
Added¶
-
Added a bounded Atheris URL-parser fuzz smoke to the primary Linux CI job, with deterministic regression seeds, acceptance invariants, network guards, and retained failure inputs. The hash-pinned engine is a CI-only tool and adds no application dependency or external account requirement.
-
primr draft --local [--model MODEL] BUNDLEwrites cited draft Markdown and DOCX from verified prep evidence through an installed local or explicitly configured private-network model. Dry runs inspect live capacity and report conservative timing guidance. Outputs include source excerpts, coverage, model/quantization/runtime provenance, and zero model API spend; they are explicitly unvalidated drafts. Busy runtimes preserve non-report checkpoints. - Local-stage evaluation discovers drafts inside flat prep bundles and copied or renamed directories, records their artifact-owned baseline provenance, and excludes local/self comparisons from promotion evidence and model recommendations. Malformed draft markers cannot become provider baselines.
Fixed¶
- Redirect followers request each
Locationtarget exactly asurljoinresolved it. Normalization remains the SSRF and identity check, so a server that canonicalizes/en-usto/en-us/no longer loops until too many redirects. - The default OpenRouter utility model is
google/gemini-3.1-flash-lite.google/gemini-2.5-flash-litestays in the catalog for an explicit override and expires 2026-10-20. The successor was present on the OpenRouter model list on 2026-10-12, with no expiration date. - OpenRouter full-run cost guidance now matches the 2026-10-12 dry run: about $1.07, from an estimator total of $1.0655. Prompt-cache savings are not assumed, and OpenRouter credit-purchase fees are not included.
-
primr prepreportscompletedonly when current, human-readable first-party pages were captured. A run with no such pages ispartial, names the concrete reason, and suggests a next step the prep command accepts. The manifest records each source class as captured, queried and empty, queried and failed, or not queried. -
Section writing receives its writer and coherence callbacks from the research coordinator, removing the stage's import back edge while preserving facade helper patch seams, recovery, routing, source fencing, and section order. The largest import-cycle component shrinks from 11 modules to 10, with no added production module and a tighter architecture gate.
-
Remove dead local assignments, redundant imports, and unused implementation loggers identified by code scanning. Preserve document rendering, URL port validation, compatibility exports, and retry behavior. Explain deliberate best-effort exception recovery at the owning handlers.
-
URL validation now rejects a port-only authority such as
https://:443when a host is required, matching its documented contract. Explicitrequire_host=Falseand custom hostless schemes remain supported. -
Restricted TypeScript adapter process-input fuzzing to strings that can cross the OS argument boundary, preventing surrogate encoding failures before the adapter runs while preserving malformed JSON coverage.
-
Usage history survives tool reinstallations. Usage tracking, doctor, and evaluation auto-staging share the durable per-user history, honoring
PRIMR_DATA_DIR. Legacy history is imported atomically without replacing distinct existing records, with original bytes retained for recovery. Malformed histories are preserved and reported instead of silently erased; explicit library storage paths remain isolated. Cooperating local writers serialize migrations and saves, preserving other processes' committed usage and keeping failed saves retryable without duplicating session records. -
Added a root security-policy entry pointing to the existing reporting and threat-model documentation so repository security tooling can discover it.
-
First-run installers prefer uv, select Python 3.12 through 3.14 explicitly, preserve existing pipx and editable installs, and give package-manager guidance when pipx cannot safely be bootstrapped.
primr updaterecognizes uv tool environments. Install docs now use explicit supported Python versions and remove staledoctor --localexamples. Missing provider keys point to the $0primr prepevidence path. Refs #202. -
Sparse pages are distinguished from access blocks. Small HTML responses no longer count as soft blocks solely because of their byte length. Reachable but insufficient pages retain their HTTP status and content assessment through tier exhaustion, and the CLI explains why additional sources are needed. Explicit challenge, status, and content-quality checks remain in effect.
-
Company evidence requires an identity link. Wikipedia candidates must match the target website through current Wikidata official website claims. Hiring collection tries first-party careers pages before guessed ATS tenants, checks guessed boards and search results for employer identity, and retains identity evidence in posting indexes. Prep excludes unverified hiring rows and reports identity-linked posting counts. Arbitrary customer or tool links cannot verify an employer or promote unrelated roles on a mixed board.
-
Local metadata and chat transports bypass environment proxies and refuse redirects. Draft model selection rejects detectable cloud names and remote aliases without pulling models or using a cloud fallback.
- Captured prep text is reconciled with its source index before draft citation assignment, including in copied evaluation inputs. Embedded URL framing cannot turn captured page text into a hiring citation or silently truncate evidence. New prep rows include per-source stripped-text digests; valid legacy whitespace and metadata-only duplicate URLs remain supported.
[1.39.17] - 2026-09-17¶
Added¶
- OpenRouter default single-key provider routing. OpenRouter is now the preferred default provider route whenever
OPENROUTER_API_KEYis configured, providing single-key coverage across utility (google/gemini-2.5-flash-lite), writing (openai/gpt-4.1-mini), and reasoning (deepseek/deepseek-v3.2). Per-run cost is the dry-run estimate. - Provider override and explicit opt-out controls. Added automatic priority for OpenRouter with explicit opt-out support via
PRIMR_OPENROUTER_ENABLED=0and provider overrides viaPRIMR_PROVIDER=geminiorPRIMR_PROVIDER=xai.
Changed¶
- Global strict typing baseline. Enabled
check_untyped_defs = Trueandwarn_redundant_casts = Trueinmypy.iniglobally across all 483 source files, raising the default type verification floor. - Persistent agent instructions refined. Updated
CLAUDE.mdandAGENTS.mdwith explicit operating loops, consequence-based autonomy, system-level defect fixes, dependency hygiene invariants, and OpenRouter default routing guidelines. - Documentation refresh across guides. Updated
README.md,docs/OPENROUTER.md,docs/API_KEYS.md,docs/CONFIG.md, anddocs/RUN_MODES.mdreflecting OpenRouter as the preferred single-key provider default.
Fixed¶
- OpenRouter preflight connectivity resilience. Preflight checks in
src/primr/core/cli_preflight.pynow bypass Google Gemini network probes when OpenRouter is the active provider and Gemini is not explicitly required, preventing unneeded API key failures. - Run budget spend calculation safety. Hardened
observed_session_spend()insrc/primr/utils/run_budget.pyagainst unconfigured Gemini keys and integrated token usage tracking across all registered provider instances. - Concurrent chat logging race condition. Added microsecond timestamps to atomic temporary files in
src/primr/utils/chat_logger.pyto eliminate same-process collision during parallel section writes.
[1.39.16] - 2026-09-16¶
Added¶
- Google Gemini 3.8 Flash model support. Added
gemini-3.8-flashto the model registry with 1M input context, 64k max output tokens, and explicit pricing ($0.75 input, $3.75 output, $0.075 cached input per 1M tokens). - Expanded OpenRouter model catalog. Added curated models including
google/gemini-3.8-flash,google/gemini-3.7-flash,google/gemini-3.1-flash-lite,openai/gpt-5.4-mini,openai/gpt-5.4-nano,deepseek/deepseek-chat,deepseek/deepseek-r1,anthropic/claude-sonnet-4.6,anthropic/claude-haiku-4.5, andmeta-llama/llama-3.3-70b-instruct. - Granular OpenRouter role overrides. Added
PRIMR_OPENROUTER_UTILITY_MODEL,PRIMR_OPENROUTER_WRITING_MODEL, andPRIMR_OPENROUTER_REASONING_MODELenvironment variables to configure models per stage without source code edits. - Explicit OpenRouter provider selection. Added
PRIMR_PROVIDER=openrouterandPRIMR_OPENROUTER_PREFERRED=1to prioritize OpenRouter over direct provider keys when both are configured. - OpenRouter parameter requirement tuning. Added
PRIMR_OPENROUTER_REQUIRE_PARAMS=0support for models that reject optional parameters (such as custom temperature). - Evaluation bakeoff script enhancement. Added
--include-openrouteroption and Gemini 3.8 Flash toscripts/eval/provider_bakeoff.py, with early credential verification to skip invalid or test keys cleanly.
[1.39.15] - 2026-09-13¶
Security¶
- MCP HTTP validates trusted hosts and browser origins. The server now
enables the SDK transport guard. Local clients retain safe defaults; wildcard
listeners require explicit
MCP_ALLOWED_HOSTS, and browser origins are separately configured throughMCP_ALLOWED_ORIGINS. Forwarded headers do not establish trust. Real transport regressions cover current and legacy clients.
Fixed¶
- Portable plugins retain state outside their installation. Generated
Agent Plugins configuration launches in
${PLUGIN_DATA}. Installed-layout tests verify controller readiness, journal continuity, and retained artifacts across plugin replacement without model calls. - VS Code has its own native MCP example. The workspace snippet uses
servers, while portable Agent Plugins and other native configurations retain their respective schemas. - Azure ingress matches the MCP transport contract. Templates configure the exact public authority, require explicit browser origins, and allow the current MCP request headers and legacy session operations. The compiled ARM template is regenerated from Bicep.
- Dry-run tests isolate optional gateway settings. Legacy and single- provider cases cannot inherit local OpenRouter opt-in configuration.
Documentation¶
- Next work follows verified gaps. The current-source review records MCP and Agent Plugins currency, runtime evidence, and remaining acceptance limits. The queue prioritizes bounded compatibility fixes before ownership cleanup and independently validated report-quality measurements.
- Evaluation protocols distinguish agreement from correctness. Known-error cases, material-fact coverage, abstention, and human review of sampled unanimous verdicts supplement disagreement review. Historical pilot results no longer authorize automatic gate arming or imply production-wide quality.
- The development contract preserves a reliable working loop. Coding guidance names current verification scope, canonical ownership, evidence for integration claims, and resumable scratch state while preserving the separate operating guide and existing spending and release controls.
[1.39.14] - 2026-09-09¶
Security¶
- Dependency floors cover the published package as well as CI. The search
stack now requires
httpx2>=2.12.0, covering CVE-2026-84379, CVE-2026-84380, and CVE-2026-84382. Documentation builds requiremkdocs-material>=9.7.7for CVE-2026-73295. The locked HTTP client and transport both use 2.12.0.
Fixed¶
- Container dependency exports match the reviewed lockfile. Regenerated the hash-locked deployment requirements alongside the HTTP dependency updates, resolving the cross-platform CI failures in the separate updates.
- Release tooling uses an available, non-yanked build frontend. Replaced
the yanked
build1.5.1 lock with 1.6.0. - Provider-readiness tests isolate local gateway configuration. The no-provider, OpenAI-only, and legacy dispatch regressions clear OpenRouter settings so an operator's enabled gateway cannot change their expected results. Legacy rejection tests also assert that research is never started.
Documentation¶
- Maintenance and planned architecture work remain distinct. The release records and package versions agree on 1.39.14. The orchestration back-edge work remains open as the 1.39.15 candidate with its original exit criteria.
- Dependency maintenance includes container exports. The contributor guide records the pinned uv version and both regeneration commands. The roadmap consistency test reads the current candidate instead of pinning an old one.
[1.39.13] - 2026-09-02¶
Fixed¶
- Budgeted dry runs report launch readiness honestly. A dry run whose
estimate exceeds
--budgetnow setsexecution_ready: falseinstead of reporting a launch-ready provider recipe. Invalid ceilings also return a structured error before any model call.
Changed¶
- Budget previews expose the complete decision. Human output shows the
supplied ceiling and estimate. JSON distinguishes provider readiness from
final execution readiness and includes the ceiling, estimated cost, and
within_budgetresult. The same validation and comparison functions now serve the preview and execution preflight.
Documentation¶
- The active queue is executable and versioned. The roadmap now owns
dependency order and long-range gates, while
NEXT_STEPS.mdcontains one bounded implementation card, exit criteria, and the release-version update protocol. Future work uses readiness gates instead of delivery dates or effort estimates. - OpenRouter's $10 ceiling path is explicit. The README and operator guides show the separate routing opt-in, per-run ceiling behavior, approval gate, runtime checkpoint limits, and independent provider-side spending control.
[1.39.12] - 2026-09-01¶
Added¶
- Optional OpenRouter paid gateway preview. A curated Standard recipe now
routes utility, writing, and reasoning through explicitly priced OpenRouter
models across CLI, MCP, A2A, and supervised-worker execution. Key setup and
auth-only validation are available through
primr keys.
Security¶
- A stored key is not spend consent. OpenRouter generation remains disabled
until
PRIMR_OPENROUTER_ENABLED=1, and every paid run still requires the normal fresh estimate and explicit approval. - Gateway requests fail closed on price and privacy. Each request applies registered input/output price ceilings, denies data-collection providers, defaults to zero-data-retention endpoints, and rejects unpriced custom model slugs before transport. OpenRouter keys are redacted from logs.
Changed¶
- Gateway accounting uses billed cost when supplied. OpenAI-compatible
response normalization now accepts finite nonnegative
usage.costmetadata, allowing OpenRouter's exact response charge to flow into run accounting while retaining conservative token estimates when exact cost is unavailable. - Provider-facing labels are no longer Grok-specific. Standard pipeline phase and summary labels name the selected provider while preserving the existing xAI labels for xAI routes.
- Python 3.15 compatibility is exercised without overstating support. A
hard Linux preview lane runs the locked suite on Python 3.15 while the release
is still a candidate. Stable classifiers remain 3.12 through 3.14, and the
installation guide records the current Windows
pywin32wheel blocker. - Doctor contains native dependency failures. The Playwright runtime probe
runs in an isolated child process, so an incompatible preview-runtime wheel
becomes an actionable warning instead of terminating
primr doctor. - Python 3.15 browser tiers fail closed. Primr marks Playwright, Patchright,
and the Playwright-backed vision tier unavailable before entering the current
incompatible
greenletsync runtime. Safe collection tiers continue through the normal fallback chain instead of risking an interpreter crash.
Documentation¶
- OpenRouter has a focused operator guide. The README stays a front door
and links to setup, curated pricing, custom-model requirements, privacy
controls, current boundaries, and the cost gate in
docs/OPENROUTER.md.
[1.39.11] - 2026-09-01¶
Changed¶
- Primr Zero confirmation guidance is unambiguous. The README, roadmap, and
synchronized skill now state that
primr prepis already noninteractive and never needs a piped yes response or--skip-confirm; that flag remains only for an explicitly approved provider-backed automation command.
Fixed¶
- Final reports no longer ship encoded presentation entities. The shared
final-artifact canonicalizer now decodes safe named, numeric, and nested HTML
entities and normalizes nonbreaking spaces while keeping encoded angle
brackets inert. Provider-backed output paths and the zero-cost renderer now
prevent prose such as
S&Sfrom reaching their customer-facing deliverables.
Documentation¶
-
The root README remains a focused front door. Installer scripts, upgrade behavior, PATH troubleshooting, and source-checkout setup now live in a linked installation guide; entity-normalization details live in the artifact guide, and confirmation details live in the operator guides.
-
Company analyst product contract. The canonical product direction now keeps the bare company-and-website invocation, evidence-grounded long-form Strategic Overview, YAML-defined strategy documents, Word delivery, free-first routing, approximately $1 approved Standard target, analyst-quality evaluation, and synchronized GitHub/PyPI release discipline ahead of supporting architecture, backend, ledger, memory, or agent work.
- Run-scoped epistemic ledger contract. The design now separates retained evidence, source-grounded findings, strategic inferences, and diagnostic hypotheses before report prose. It specifies digest-bound evidence anchors, bi-temporal fields, shadow-first evaluation, claim-aware section usage, and an experimental declarative semantic firewall without adding a graph platform or changing current report behavior.
- Memory and interchange sequencing corrected. v1.43 now owns governed run-ledger history, v2.0 owns the indexed claim/proposition store and priming, and v2.x owns Strategy Delta. Native run JSON/JSONL and SQLite remain canonical in their scopes; OKF stays an explicit export projection. The shipped profile export is documented as OKF-shaped rather than conformant.
[1.39.10] - 2026-08-25¶
Changed¶
- Foreground terminal detection is shared across setup and maintenance. Update, init, doctor fix, key setup, banner detection, and console capability detection now use the same exception-safe stream check.
- The legacy packaged module follows the public CLI boundary.
python -m primr.primr_clidelegates toprimr.cli_entry, matching the console script andpython -m primrbehavior.
Fixed¶
- Unavailable input cannot select a default-yes action. An empty answer still uses the displayed default, while EOF and closed or detached streams fail closed.
- Setup and key entry handle disappearing terminals cleanly. Hidden secret prompts now return an actionable nonzero result instead of leaking an input exception or continuing after the terminal disappears.
- Automated updates require a visible prompt or
--yes.primr updatechecks both input and output terminal capability before inspecting the installation method, and distinguishes unavailable confirmation input from a user cancellation. - Damaged output streams no longer break capability detection. Banner,
console, and terminal probes fall back to noninteractive capabilities when
isatty()is missing or raises.
[1.39.9] - 2026-08-25¶
Changed¶
- Noninteractive approval guidance is command-specific. The README,
roadmap, agent integration guide, operator guidance, portable skill mirrors,
and CLI help now distinguish the standard provider-backed
--skip-confirmsignal from the experimental orchestrator's approved--max-cost <usd>ceiling.
Fixed¶
- Every paid CLI prompt detects background execution before reading input. Research, vendor research, standalone strategy generation, batch research, batch enrichment, model-backed improvement, orchestration, Accordion tests, paid evals, skill packs, and cloud calibration now require usable input and output terminals before opening an interactive approval prompt. Background jobs fail before billable work and report the exact explicit approval flag needed to resume.
- Unavailable input is no longer reported as a user cancellation. EOF, detached streams, and closed streams map to missing approval across direct confirmation paths. Keyboard interrupts and explicit negative answers remain voluntary cancellations.
- Prompt capability checks fail closed on damaged standard streams. Shared terminal detection safely handles missing, closed, or detached input and output streams, and shared yes/no prompts no longer leak stream exceptions.
- Approval state is bounded and machine-checkable. Research runtime plans now type their status vocabulary explicitly, preventing new unhandled states from silently entering command dispatch.
[1.39.8] - 2026-08-25¶
Fixed¶
- Background CLI launches preserve the approval contract. Agent guidance
now replaces
--dry-runwith--skip-confirmafter explicit approval before starting a provider-backed background job. A noninteractive research command without that signal starts no provider work and is no longer mislabeled as a user cancellation when its input stream is closed. - Release verification tolerates normal PyPI propagation delay. Published filename and hash verification now waits for nearly three minutes before failing, while retaining exact, fail-closed artifact equality checks.
[1.39.7] - 2026-08-22¶
Changed¶
- Fast validation has one-way ownership. The stage receives its report
reviewer through the research composition boundary and imports regeneration
and observed-spend behavior from their existing owners. This removes
fast_run_validationfrom the package-inclusive orchestration cycle, reducing that component from 12 modules to 11 with no new production module or public CLI, MCP, A2A, or report-contract change. - External-source independence uses one URL boundary. Fast collection, gap filling, report and strategy enrichment, structured research, and scrape-only collection now share canonical hostname comparison instead of comparing raw URL strings.
Fixed¶
- Malformed cross-validation results degrade safely. Successful recovery results are type-checked, bounded to the documented finding limits, and normalized before enrichment or contradiction handling. A null, list-shaped, or partially malformed model response no longer crashes a report run.
- Timed-out enrichment workers cannot hold process shutdown open. Abandoned validation pools now use the established running-worker detachment seam after canceling queued work.
- Optional validation diagnostics cannot discard a report.
cross_validation.jsonis replaced atomically, and persistence or JSON encoding failures are logged without failing the completed report stage. - First-party pages no longer masquerade as external evidence. Scheme and
wwwvariants plus company subdomains are filtered consistently, while hostname lookalikes remain eligible and malformed candidates fail closed. - Circuit-breaker property coverage is deterministic under load. The retry-delay invariant no longer races a 10-millisecond half-open transition while coverage tracing or a busy CI runner is active.
- Banner capability tests are isolated from the host terminal. Truecolor
detection cases now define their complete color and terminal preconditions
instead of inheriting
NO_COLORorTERM=dumbfrom an agent or CI host.
[1.39.6] - 2026-08-22¶
Changed¶
- The main orchestration import cycle is nearly halved. Ten modules now depend directly on their doctor, update, recon, workspace, model-routing, source-relevance, spend-accounting, regeneration, and report-cleanup owners. The package-inclusive component falls from 22 modules to 12 without adding a production module or changing CLI, MCP, A2A, or report behavior.
- Composition dependencies are explicit. CLI initialization receives its doctor runner, and guarded dispatch receives its passive update callback, instead of generic helpers importing their high-level callers.
- Architecture regressions are pinned. Direct owner tests and
fresh-interpreter tests cover both import orders for every removed pair;
cli.pyandresearch_agent.pyalso receive tighter line ceilings.
Fixed¶
- Passive update notices cannot reverse successful research. Cache, network, and console-output failures are contained across the complete notice path, including a closed output pipe after a report finishes.
- Source relevance accepts only declared integer selections. Boolean and fractional JSON values no longer select unrelated sources, and the retained evidence keeps its original deterministic order.
- Corrupt local collection caches recover cleanly. Invalid or negative cached metrics now invalidate the resume snapshot and trigger fresh collection instead of terminating the run during cache reconstruction.
[1.39.5] - 2026-08-22¶
Security¶
- Agentic orchestration uses the central SSRF seam. Every pre-tool hook now
receives the company URL, and
SSRFGuardHookdelegates directly toutils.security.is_safe_urlinstead of maintaining a second validator. - Outbound browser and A2A logs redact URL secrets. Blocked Playwright requests, A2A hook decisions, discovery/RPC errors, redirect failures, and delegation exceptions omit userinfo and query strings.
Fixed¶
- Eval batch caps survive per-run counter resets. Each started missing-cell run reserves its planning estimate, and the next run receives only the uncommitted remainder as its runtime budget. Failed or partial starts still reserve their quote. Negative and non-finite fixed estimates or caps fail closed before provider work.
- Accordion runtime budgets account for its actual call paths. The accepted
Deep Research task contributes its planning cost, direct Gemini section
responses enter the shared run ledger, and the next section is checked
against a conservative per-call estimate. Non-finite
--budgetvalues are rejected. - Accordion reads current Deep Research responses. Completed Interactions
use the shared
steps/output_textparser with the deliberate legacyoutputsfallback. A run with no completed report sections is a failure, not a successful header-only artifact. - Per-run Gemini compatibility usage resets with other counters. Long-lived and sequential processes no longer carry direct Gemini SDK usage into the next run, while summaries and budget checkpoints share one cost function.
- The synchronous Accordion wrapper uses the shared async bridge. It now follows the repository's single sync/async boundary contract.
Changed¶
- Extracted eval execution and staging from
core/cli.py, lowering the pinned CLI size ceiling while keeping the public command contract unchanged.
[1.39.4] - 2026-08-21¶
Security¶
- Unparseable resolved addresses fail closed. A
getaddrinforesult thatipaddresscannot parse (scoped IPv6, garbage sockaddr) is blocked instead of treated as public. The parallel DNS check invalidate_url_for_requestdoes the same. - IPv4-translated and IPv4-compatible embeddings are unwrapped. SIIT
::ffff:0:0:0/96and deprecated::/96encodings of loopback/metadata no longer bypass the SSRF guard. - Browser egress aborts unknown schemes.
data:/blob:/about:stay local;file:,ftp:,ws:, and other non-HTTP schemes are denied.
Fixed¶
- MCP
generate_strategybinds the approved ceiling. After the token check it activates the same--budgetrun-budget the research path uses, then clears it. primr orchestrateCostGuard is no longer a paper ceiling. It registers the run-budget's hook, syncs session LLM spend after each stage, and blocks further stages once remaining is exhausted — even with a $0 estimate.- Sequential
--budgetstops later platforms and vendors. Standalone strategy and vendor-research loops skip remaining paid tasks once the ceiling is reached. - Library
process_batchis fail-closed.skip_confirmdefaults toFalse(CLI already passed the parsed flag). The fallback estimate uses the planning floor so cheap historical samples cannot under-approve. - Non-fast MCP strategy generation respects the run budget. Collection that already exhausted the ceiling no longer starts the priced AI strategy.
[1.39.3] - 2026-08-21¶
Security¶
- MCP/A2A URL validation uses the shared SSRF guard. The parallel
URLValidatorimplementation missed IPv4-mapped IPv6, unspecified::, and NAT64 (64:ff9b::/96) embeddings of loopback and metadata addresses. - Connect-time DNS pinning on remaining fetch seams. A2A client requests
and sitemap
make_requestnow pin the resolved IP (Host/SNI preserved) so a rebind between check and connect cannot reach loopback or cloud metadata. - Remote JWTs require
exp. Tokens without an expiry can no longer authenticate forever. Static admin tokens remain the documented no-exp path. - Outbound URL logs redact userinfo and query strings. Blocked/failed
safe_httprequests no longer print credentials or signed-query tokens. - pip 26.2.1 for PYSEC-2026-3721 (lockfile floor).
Added¶
- Portable Agent Plugins v1 package.
agent-plugin/now provides an experimental, schema-validated Agent Plugins v1.0.0 Working Draft artifact with the canonical Primr and Primr Zero skills plus theprimr mcpstdio server. A deterministic sync command and drift tests keep it derived from the existing skill sources without changing the Claude-specific plugin. - Blinded Standard/Premium quality evaluation contract. A pre-registered five-company, ten-artifact design now measures evidence support, confidence honesty, citation integrity, and full-document coherence with judge agreement and human adjudication. Billable runs remain estimate-gated.
- Progressive working brief (Layer 1). After fast-path scrape (+ recon),
Primr writes a free, deterministic
working_brief.md(and a dated public*_Working_Brief_*.mdunderoutput/) with incomplete banner, recon excerpt, page/source inventory, hiring counts, and still-running stages. Zero extra model calls. Inventory classifies it asworking_brief, neverprimary_report. Seedocs/design/progressive-artifacts.md. - Working brief on structured/deep collection. Premium/complete Phase 1
(
run_research) now emits the same Layer-1 incomplete brief after scrape, reusing the run folder when the orchestrator suppliesfolder_path. - MCP
early_artifact_paths. Non-terminal and completed job status includes body-free working-brief paths under the job output directory.
Fixed¶
- MCP
mode=scraperuns scrape-only. It was estimated as scrape-only (~$0.10) then executed as structured research (section writing). - QA reports are not the Strategic Overview.
classify_output_artifactno longer treats any filename containing"report"as the primary brief.primr://output/latest,by_job, andartifactsread job output paths and prefer*_Strategic_Overview_*. - HTTP MCP status/next-actions/artifacts are owner-gated. Callers who
do not own the active/latest job see idle instead of another tenant's
output_paths. - Refine rejects path-traversal company names before it globs working directories.
- Garbage numeric env values no longer crash import.
MAX_EXTERNAL_*, scrape-pilot, Playwright lazy-scroll, and banner duration fall back to defaults (same class as the earlier PDF-LLM env fix). - MCP rate limiter check-and-record is atomic, and non-positive env overrides keep the default instead of disabling the limiter.
- Anthropic keys redact as Anthropic, not as OpenAI.
- Accordion and eval no longer launch billed work from a flag or dry-run.
--test-accordionprints a Deep Research estimate, supports--dry-run, and requires--skip-confirmor an explicit yes.--eval --eval-run-missingand--eval --eval-llm-judgetreat cost caps as ceilings, honor--dry-run, and require the same approval. Deep Research start paths fail closed underdisable_model_calls(). - Skill-pack
--budgetis a ceiling, not approval.primr skillsstill quotes and requires--skip-confirmor yes even when a budget covers the estimate. --resume-localreuses paid collection instead of repeating it. A durable collection cache skips scrape/summarize/search on resume. Structured collection no longer deletes_raw_scrapesafter summarize. Resume without--output-dirrestores the recorded public output directory.--resume-latest --output-dirwrites recovered artifacts there. Job metadataoutput_diris the fallback when the flag is omitted.- MCP progress leaves
scrapingwhen later stages start. Progress messages advance EXTRACTING / DEEP_RESEARCH / WRITING / QA. Missing model usage no longer reconciles as$0.00. - Deep/standard runs no longer stamp
completedwithout a report. A missing or empty primary artifact recordsfailedso resume can retry instead of launching a second paid Deep Research job. - Final-report cleanup keeps the working folder. ZIP archive still runs;
rmtreeofworking/<Company>/is gone so resume evidence and Windows file locks survive a DOCX miss. - MCP report save fails closed on empty content. Empty orchestrator
results raise instead of completing a header-only
.md. Filenames use the shared sanitizer andStrategic_Overviewcontract name. - Incomplete paid partials are not primary reports. They are named
*_Incomplete_Overview_*so inventory and MCP report reads cannot treat them as the Strategic Overview. artifacts_availableis on-disk on every status surface. MCPprimr://research/statusand A2A terminal status share the sameis_file()helper ascheck_jobs.- Run-state saves no longer truncate on lock failure. Persistent
PermissionErrorkeeps the last good_run_state.json. - Section assembly uses the current run folder.
generate_final_reportcan load sections from the activefolder_pathinstead of the newest sibling directory. - MCP/A2A extra kwargs cannot under-price a full run. Estimates ignore
unbound
lite_strategy/grok_tierfields the worker does not receive. - Approval tokens cap the runtime budget. Caller
max_estimated_cost_usdcannot exceed the approved token ceiling. - Unpriced model usage is not recorded as
$0.00. Stage usage deltas and MCP actual-cost reconciliation leave costnullwhen a model has no registry price. - Prep cannot spend via Gemini Vision. Tracing no longer constructs the
scrape orchestrator with vision enabled,
get_orchestrator(enable_vision=False)strips an already-created vision tier, and the vision scraper fails closed underdisable_model_calls()before taking a screenshot or calling Gemini. - Keyless link selection uses heuristic scoring. When models are disabled
or the selector fails, prep keeps
/about,/investors, and/productsinstead of the first N discovery-order URLs. - Recon no longer treats Google Trust / SES / ACM as a cloud platform. Those remain cert/email signals; only DNS/CDN/appservice fingerprints declare AWS/Azure/GCP in the host packet and strategy context.
- MCP report reads no longer treat a working brief as the report.
classify_output_artifactlabelsworking_briefand report filters skip it. - MCP/prep recon from a running event loop. Standalone evidence collection
no longer uses bare
asyncio.run()for DNS recon. MCPgenerate_skill_pack(an async handler) was silently skipping tenant/DNS evidence. The collector now uses the shared sync/async bridge and writes recon atomically. - Prep dry-run URL validation.
primr prep --dry-runrejects invalid or non-HTTP company URLs without network access instead of previewing a plan that the real command cannot run. - Model-policy coverage on remaining LLM seams. Provider
chat(), xAI browse,AIClient.generate(), and the OpenAI-compatible chat helper now fail closed when model calls are disabled, matchingllm()/grok_llm(). - Invalid PDF-LLM env no longer crashes scrape import. Garbage
PRIMR_PDF_LLM_*values fall back to the zero-spend defaults instead of raising at import and breaking prep/scrape. primr renderkeeps host report headings. Filename is no longer forced as a document title (which stripped the first H1, often1. Executive Summary). Directories are rejected. Empty DOCX output is a failure. Fenced code blocks are no longer parsed as tables.- Working-brief public date matches other deliverables. Timezone-aware timestamps use the local calendar date, not UTC.
--analyze-reporthonors host-written H1 outlines. Numbered H1 sections and an H1Sourcesappendix now count for structure and citation integrity, matching the Primr Zero report contract.- Current Gemini request and pricing contracts. Gemini 3.7 Flash is an eval-only candidate, production defaults remain unchanged, direct Gemini paths omit unsupported sampling controls for current model families, and Gemini 3.6/3.7 dry-run prices apply Google's published January 1, 2027 rate change by pricing date.
- Accepted Deep Research jobs retain durable recovery state. Pending File Search Stores are protected from orphan cleanup, accepted cancellation keeps its store and recovery record, terminal resume cleans the store only after durable output, and a minimal fsynced receipt survives primary registry write failure without copying prompts or arbitrary metadata.
- Gemini access checks are model-free.
primr --check-quotaand the legacy preflight validator now use model metadata access instead of generating tokens, report truthful failure status, and defer all price claims to the canonical dry-run estimator. - Model-backed improvement cost gates.
primr improve --improve-agenticandprimr refinenow provide bounded dry-run quotes, require explicit approval, enforce--budgetthrough pre-stage reservations, and expose one-object JSON estimate, refusal, and result contracts. Deterministicprimr improveremains local, model-free, and ungated. - Paid Premium partial jobs close only after durable output. Failed Deep/Premium runs with usable paid content publish an explicitly incomplete Markdown artifact and acknowledge the accepted provider interaction only after that file is non-empty and durable.
- Single-call fallback pricing keeps its request tier. A recorded one-call xAI bucket below the long-context threshold now uses the published short tier when exact provider cost is unavailable. Ambiguous multi-call buckets remain conservatively high-tier.
- Reproducible uv toolchain. CI, deployment-lock documentation, export tests, and regenerated container requirements now agree on uv 0.11.33, the latest patch retained on the verified 0.11 toolchain line.
- Current Gemini Deep Research and File Search contracts. Interaction
response parsing now reads the current
steps/model_output/ content shape while retaining a deliberate fallback for persisted legacyoutputsresponses. File Search uploads wait for the provider operation to finish before a paid research interaction can use the store, and the declaredgoogle-genaifloor now matches the current Interactions SDK requirement. - Grok 4.20 registry and estimates. Official dated IDs and rolling aliases now share the published 1M context, $1.25/$0.20 cached/$2.50 short-context rates, and inclusive 200k $2.50/$0.40 cached/$5.00 long-context rates. Static xAI-only cost guidance and boundary tests reflect the corrected registry.
- Skill-pack spend approval and runtime ceiling.
primr skillsnow repeats its dry-run quote before execution, requires explicit approval or a covering--budget, and checks observed run spend between paid phases. The legacy per-role setting is no longer described as an enforceable parallel-call cap. - MCP governance facts survive execution. Research jobs now journal a non-secret estimate and approval envelope before worker launch. Successful and terminal manifests report the estimate, approval-token id, approval time, and binding status without persisting the raw token.
- MCP and A2A actual-cost audit persistence. Completed research jobs now persist run-scoped model cost after optional verification, plus accepted Deep Research tasks. Paid Premium partials reconcile once after durable publication; unmeasurable failures and cancellations remain explicitly null.
- Environment-only model spend is rejected on governed runs. Label-honesty judges, Gemini PDF extraction, and the xAI scrape surrogate cannot silently extend a CLI/MCP/A2A research run until their calls are explicit inputs to the estimate and approval shape.
- Research JSON approval is fail-closed. Provider-backed research with
--jsonnow returns one structuredapproval_requiredobject unless--skip-confirmexplicitly authorizes execution. Approved JSON runs suppress nested human estimates and update notices so stdout remains one JSON object. - Unpriced xAI scrape surrogates now fail closed. Blocked-site fallback
remains deterministic by default. The metered xAI
web_searchsurrogate requiresPRIMR_ENABLE_GROK_SURROGATE=1; the existing disable switch still takes precedence. Billing exhaustion stops the fan-out instead of being treated as an ordinary missing page. - Dependency security floor.
h2>=4.4.1prevents the resolver from selecting the version affected by PYSEC-2026-3628. - Premium context files are no longer dropped. Deep and Complete report paths upload supplied files into the dossier File Search Store alongside Stage 1 evidence and retain the existing cleanup guarantees.
- Deep/Premium verification now matches its quote.
--verifyis forwarded through deep dispatch and runs after a durable report is produced. - Premium page targets now affect generation. The target sizes dossier and section prompts as an approximate evidence-dependent writing contract, while explicitly prohibiting padding and invented claims.
- Working brief honors
--output-dir/ MCP job dirs. Public*_Working_Brief_*.mdis written under the run’soutput_dirfrom run state, not always the globalOUTPUT_DIR. - Analysis fallback no longer looks fully successful. Degraded workbook
paths use warn styling and record
analysis_status=fallback. - Lite vendor-news pricing fail-visible. Token pricing exceptions use a
non-zero floor and log a warning instead of
$0.00token cost. - CLI authorization floor matches MCP.
build_run_estimatetakesmax(planning, historical)so cheap samples cannot under-approve a run for dry-run,--budget, or launch quotes. primr orchestrateURL re-validation. Whitespace-only and invalid URLs fail closed after scheme normalization (same validate seam as research).- MCP artifact rows include binary deliverables. Metadata/hash use
binary reads so
.docxis not silently dropped; content only when UTF-8. artifacts_availableis on-disk truth. Completed jobs require at least one existing file path, not a stale path list.- Working brief hiring refresh no longer wipes URL inventory. Bounded sample URLs persist in run-state and are restored on refresh.
- Working brief zero counts and missing paths. Explicit
0pages/sources are not replaced by URL-list length; early-path inventory skips deleted files. - Unpriced model usage no longer shows
$0.00. Summary lines mark~$? (unpriced model)and warn instead of reporting free spend. - Unknown cost modes fail closed.
estimate_costmaps product aliases (full/deep/scrape) and raises on typos instead of silently pricing as scrape-only (under-approval hazard). - Cross-provider utility calls retain exact billed cost. The shared
llm()dispatch now mirrors a provider'sactual_cost_usdinto the run counters, matching the existinggrok_llm()accounting path. - Skill-pack time quotes round up. Fractional minute estimates no longer truncate to a shorter displayed runtime.
- xAI long-context cache estimates match the provider boundary. The cost model now applies xAI's long-context tier at exactly 200k prompt tokens and uses the published high-tier cached-input rate instead of the base cache rate.
- Orchestrated full runs need a report to succeed. Empty intermediate stage data no longer yields a green COMPLETED with no report path.
- OpenAI/Anthropic-only dry-run honesty. Full-mode quotes disclose that
dollars are the XAI/Gemini planning floor, set
execution_ready=falsein JSON, and point next steps at configuring XAI/Gemini rather than launch. - MCP/A2A research estimates under-approving. Estimates now forward
grok_tier/lite_strategyand authorize atmax(planning, historical)so cheap history cannot understate the approval floor. - Corrupt
_run_state.jsonsilent wipe. Unreadable state is quarantined to*.corruptwith a recovery marker instead of empty-dict overwrite. - Partial fast-run success styling. "Complete with warnings" uses warn styling, not a green success check.
- Billable confirm defaults. Interactive Proceed is
[y/N](explicit yes only), matching batch approval. - Usage tracking gaps. Standalone AI Strategy tracker failures warn instead of debug-only silence.
- Vendor freshness listing. Permission/path errors no longer look like an empty cache.
- Windows cooperative-cancel test flake. Marker wait accepts expected
content so it does not race
Path.write_textcreating an empty file before the body is flushed. - Portable plugin drift checks are cross-platform. Generated JSON manifests now compare canonically across LF and CRLF checkouts without hiding content or formatting drift.
Changed¶
- CLI contract ownership.
CommandandCLIConfignow live in a shared 202-line contract module consumed directly by CLI workflows. The operational CLI continues to re-export both names for compatibility, while the largest import-cycle component falls from 24 modules to 22 and thecli.pyline ceiling falls from 2,774 to 2,573. - Report topology and execution queue are explicit. Documentation now
distinguishes active Standard, active sequential Premium, compatibility, and
experimental paths.
NEXT_STEPS.mdis the concise next-PR queue while the roadmap remains the long-range backlog and release ledger. - Deep and Premium operator estimates match the priced Accordion plan. Run
guidance now includes the 23 sequential section calls, distinguishes the
default strategy-inclusive quote from
--no-ai-strategy, and treats live dry-run output as authoritative over static guideposts. - Model-backed improvement topology is explicit. Operator and roadmap docs
distinguish deterministic
primr improvefrom governed model-backed--improve-agenticandprimr refineexecution. - OKF direction is pinned to v0.2. The deferred findings-interchange design
now uses current
generated,sources,verified, and lifecycle semantics, reserves rootindex.mdfor navigation, and keeps Primr confidence separate from OKF verification. - Grok 4.6 registered without silent promotion. The August 12 xAI flagship is available to explicit evaluation with its 500k context window, reasoning levels, and exact short/long-context token and cache prices. Hybrid remains on the measured Grok 4.3 recipe and MAX remains version-pinned to Grok 4.5 until a bounded comparison supports a routing change.
- OpenAI GPT-5.6 family registered without silent promotion. Sol, Terra,
Luna, and the Sol alias now carry current context, output, cache-read, and
272K pricing metadata. OpenAI generation uses Responses with
store=false; production role routing remains pinned pending representative evaluation. - Provider-billed xAI costs take precedence when complete. Responses usage now records exact dollar cost when available, while mixed or partial buckets fall back to centralized token pricing so spend cannot be understated.
- Paid quality evaluation has a hard aggregate ceiling. The five-pair Standard/Premium design now starts with a zero-spend provider/API audit, then uses $5 and $15 checkpoints under an absolute $25 ceiling that includes research, cloud judges, tools, and approved retries. Early stopping cannot produce a positive Premium quality claim.
primr orchestratecost gate. Experimental orchestrated research now always prints a priced estimate, supports--dry-run, and refuses launch unless the estimate is under--max-costor the user confirms interactively ([y/N]). ACostGuardHookis always registered (explicit ceiling, or estimate + 25% after interactive yes). Handler lives incli_orchestrate.pysocli.pystays under its line ceiling.- Single-company launch requires approval. Human CLI runs show the priced
estimate and ask before provider work starts.
--skip-confirmis the explicit noninteractive approval override. - MCP cost approval is transport-independent. Cost-incurring MCP tools now
require the estimate-bound cap and approval token by default on stdio and
HTTP transports. An explicit false
PRIMR_ENFORCE_MCP_COST_CAPSvalue is an unsafe compatibility opt-out. - Honest dual-provider surfaces. OpenAI-/Anthropic-only dry-run labels and doctor copy say estimate/eval only; full execution still needs XAI or Gemini.
- Calibration inspect names undecidable Confirmed floors.
blockers.missing_decidable_confirmed_floorlists body-free report paths that block a complete hard-gate floor (1.40 freeze UX). - Docs site home and next-steps currency. Docs index leads with the same
front-door framing as the root README (agentic structured research, start
table, links into guides).
NEXT_STEPS,RUN_MODES,API/API_KEYS,JOB_STATUS, and progressive-artifacts design track orchestrate cost gate, CLI authorization floor, dual-provider dry-run honesty, and Layer 1 brief inventory behavior. - Grok 4.5 registered; MAX tier uses a versioned model pin.
grok-4.5is in the model registry with published xAI pricing (including ≥200k long-context surcharge). Default hybrid/fast reasoning stays ongrok-4.3for the measured sub-$1 recipe;--grok-tier maxnow routes to 4.5. Grok 4.3 also records its ≥200k surcharge from the current pricing table. - Grok default-routing decision. Hybrid stays on 4.3 (measured ~$0.76 with
Gemini writing; max-everywhere ~$8.5). Design record:
docs/design/grok-default-routing.md. Analysis fallback tries 4.5 after 4.3; premium xAI fallback prefers 4.5 then 4.3. Eval profilegrok45-flashliteis a promotion candidate only (not wired as default). - Dependency security floor:
cryptography>=50.0.0(CVE-2026-69247 / GHSA-537c-gmf6-5ccf). Lockfile and deployruntime-requirements.lockpin 50.0.0. - CLI operator polish. Shared Grok tier labels (hybrid/fast = 4.3, max =
4.5); dry-run uses the console seam with progressive recovery disclosure;
doctor treats keyless installs as ready and names hybrid/full (not
"standard"); root help lists
renderand--budget. - Roadmap version ladder. Clear 1.39 → 1.40… → 2.0 → 3.0 order of
operations with exit criteria and no time estimates
(
ROADMAP.md,docs/NEXT_STEPS.md).
[1.39.2] - 2026-08-02¶
Changed¶
- README shortened to a front door. Pitch, agent vs terminal start paths,
install, command table, and docs links. Operator detail (Primr Zero handoff,
mode/cost matrix, cost gate, MCP resource inventory, key tables) lives in
linked
docs/pages. PyPI long description followsREADME.md.
[1.39.1] - 2026-08-02¶
Added¶
- Progressive early-artifacts design (docs only).
docs/design/progressive-artifacts.mdsketches optional future mid-run working briefs. Not a product surface change.
Changed¶
- README re-centered on agentic structured research.
Front door leads with agent hosts and structured briefs (labels, artifacts,
cost gate), keeps a light ExampleCo CLI illustration, and avoids secondary
product stories. Package long description on PyPI follows
README.md. - ExampleCo CLI demo screenshot for README and docs site home
(
docs/images/primr-demo.png, regenerable viascripts/render_readme_demo.py). Placeholder company data only. - Planning and operator docs polish. Competitive positioning note,
post-1.39
NEXT_STEPS, RUN_MODES first-useful-output table (recon/prep while waiting), MkDocs home intro. - Deep-research
folder_pathfor stage_routes. CLI and MCP orchestrator paths pass the working folder sopremium.deep_researchcan record body-free route metadata.
[1.39.0] - 2026-08-01¶
Security¶
- Raised the
pymdown-extensionsfloor to 11.0.0 (docs extra) for CVE-2026-61632 and locked 11.0.1, keepingpip-auditclean.
Added¶
- Standing
fast.source_relevancelabeled corpus (source_relevance_standing_v1). Ships a body-free, package-local six-case keep-list corpus with required representative tags and dualcloud-baseline/codex-hostcandidates. Integrity inspection reports readiness blockers without source bodies.primr --eval --eval-source-relevance-standing-corpusscores the packaged corpus into review-only stage quality evidence. Scorecard input only; the corpus ships withpromotion_status=not_promotedand never auto-promotes host routing. - Offline host-vs-cloud comparison artifacts for source-relevance. Standing and labeled fixture evals now write body-free backend comparison JSON/Markdown (F1/precision/recall deltas, exact-match rates) plus a standing-corpus integrity sidecar. Comparison is review-only and does not arm promotion.
--inspect-source-relevance-standing-corpus. Zero-network body-free integrity inspection for the packaged standing corpus; exits before profile scorecard work when used alone under--eval. Inspection includes the corpus file sha256 and size so scorecards can bind the exact labeled snapshot measured. Source-relevance stage artifact paths now go through the same eval-id allowlist as other eval outputs.- MCP protocol tests for 2026-07-28 resource templates, private cache
hints, and
server/discover. Parameterizedby_jobresources must appear onresources/templates/list, list/discover cache hints remainprivate, andserver/discoveradvertises2026-07-28support plus cost-gate instructions without a session handshake. - Fast-pipeline capability-router production wiring.
fast.research_deepening,fast.analysis_workbook,fast.cross_validation(reasoning),fast.report_sections,fast.trust_polish,fast.strategy_generation(writing), and optionalfast.label_honestyresolve throughresolve_stage_model, record body-freestage_routesmetadata, and fail closed for agent/local profiles without a qualifying adapter. Cloud remains the validated baseline. premium.deep_researchcapability-router wiring. Premium deep research resolves to the Gemini Deep Research agent backend (supports_deep_research), records body-free route metadata, and fails closed without launching the agent when no deep-research-capable backend is available.
Changed¶
- MCP server now speaks specification revision 2026-07-28 natively.
Migrated from MCP Python SDK 1.x to v2 (
mcp>=2.0.0,<3). One server now serves both protocol eras on stdio and streamable HTTP: modern clients get the stateless per-request protocol withserver/discover, while older clients keep the legacyinitializehandshake. The dependency previously had no upper bound, so fresh installs resolving SDK v2 against the v1 integration would have failed at import time; the pin now tracks the supported major. - Spec-native metadata for MCP clients. List and read results carry
2026-07-28
ttlMs/cacheScopecache hints (allprivate— responses are auth-scoped), the server advertises identity (name, version, instructions) throughserverInfoandserver/discover, and the parameterizedprimr://.../by_job/{job_id}resources are now discoverable viaresources/templates/listin addition to the plain listings. - Protocol-correct error codes. Unknown tools, resources, and prompts now
return JSON-RPC
-32602(Invalid Params) instead of surfacing asisErrorresults or internal errors, matching the 2026-07-28 error-code alignment that retired-32002.
[1.38.0] - 2026-07-22¶
Added¶
- AWS Bedrock is now routable for research runs (main-process). Registered
the Amazon Nova models (
us.amazon.nova-micro-v1:0,-lite-,-pro-) with real prices, and wired the model→provider router and the standard-pipeline dispatch so a stage model set to a Nova id (e.g.AI_REASONING_MODEL) runs through the BedrockconverseAPI and prices correctly through the cost gate. Bedrock routing is refused inside a supervised MCP worker — AWS credentials are deliberately never inherited by workers, and a regression test pins that boundary. - Azure AI Foundry deployments are now routable (main-process). A Foundry
model id is a per-user deployment name, so the operator declares the
deployment and its pricing via env —
AZURE_OPENAI_DEPLOYMENTplus eitherAZURE_FOUNDRY_PRICE_AS(price/spec as a registered model) or explicitAZURE_FOUNDRY_INPUT_PRICE/AZURE_FOUNDRY_OUTPUT_PRICE. primr routes the selected stage to the Foundry endpoint and prices it from the declaration; nothing is guessed into the cost gate, and a run fails closed (unknown model) if pricing is not declared. Like Bedrock, Foundry routing is refused inside a supervised worker.
[1.37.2] - 2026-07-22¶
Added¶
- Registered the July 2026 Gemini models
gemini-3.6-flash($1.50/$7.50) andgemini-3.5-flash-lite($0.30/$2.50) in the model registry with real prices, so they are selectable and eval-gateable. Per the model-selection policy they are available but not promoted to a default tier (a default repoint is decided by eval on output $/1M).gemini-3.5-flash-cyber(a restricted dual-use pilot) andgemini-3.5-pro(still partner-testing) are intentionally not registered yet.
[1.37.1] - 2026-07-21¶
Added¶
primr render <file>.md— zero-cost Markdown → DOCX/TXT. Exposes the existing renderer as a standalone subcommand (no model calls, no network) so any Markdown report gets the same.docx/.txtartifacts as a provider-backed run. This closes the "no DOCX on the Primr Zero path" gap: the host-assisted flow writes Markdown, andprimr rendergives it deliverable parity.- Primr Zero now produces the full artifact set at $0. The
primr-zeroskill instructs the host to render each report to DOCX and to optionally write the AI Strategy itself (host-written from the same evidence, no Primr model spend), so a quota/subscription-host run yields the same Strategic Overview + AI Strategy in.mdand.docxas a paid run — the same outputs regardless of how the report was processed.
Security¶
- Bumped
pyasn1to 0.6.4 (CVE-2026-59885, CVE-2026-59886). Transitive dependency; the deployment lock exports were regenerated to match.
[1.37.0] - 2026-07-21¶
Changed¶
--ai-strategy-onlynow defaults to the ~$1 lite engine. Standalone AI strategy generation uses the Pro reasoning model by default (typically under $1, 2-3 min) instead of Deep Research. Opt into the thorough Deep Research engine with the new--deep-researchflag (~$2.50/task).--dry-runreflects the selected engine.--refresh-vendor-researchis now freshness-aware. It reuses vendor research (AI news) that is newer than the freshness window and regenerates only stale or missing docs, instead of forcing a paid Deep Research task on every run. The shared per-user cache is unchanged.- AI news (vendor research) now defaults to a grounded lite engine (~$0.30),
not Deep Research (~$2.50). A single Gemini + Google Search grounded call
produces a current, cited vendor brief for a fraction of the cost; the
heavyweight Deep Research engine is opt-in via
--deep-research. A default--refresh-vendor-researchon one platform is now ~$0.50 total instead of ~$2.71.GeminiProvider.search_and_summarizeadds the live-search capability; the dry-run estimate prices lite refresh as a metered model call.
Added¶
- Two new inference providers: Microsoft Foundry and Amazon Bedrock. Both are
full providers (chat, usage accounting, retry/backoff, credential validation)
registered in the provider registry so
primr keys test,doctor, and routing see them. Foundry reuses the coreopenaiSDK against Azure's OpenAI-compatible/openai/v1/endpoint (AZURE_OPENAI_API_KEY+AZURE_OPENAI_BASE_URL/AZURE_OPENAI_ENDPOINT) — no extra dependency, and unlocks ultra-cheap Phi-4 reasoning plus GPT/Llama/DeepSeek on Azure. Bedrock uses the boto3bedrock-runtimeconverseAPI (provider-agnostic across Claude/Nova/Llama/Gemma/DeepSeek), authenticating via the standard AWS credential chain or a Bedrock API key (AWS_BEARER_TOKEN_BEDROCK); install withpip install 'primr[bedrock]'.primr keys set foundry|bedrockandkeys testrecognize both. The Bedrock provider resolves its region fromAWS_REGIONor anaws configure/profile default, so it works with a standard AWS setup. Verified end-to-end deployment-to-teardown IaC lives inexamples/deploy/(Azure Foundry Bicep deploying Grok; AWS Bedrock CloudFormation for a least-privilege invoke policy + guardrail). primr keys test— live, auth-only key validation. Validates that each configured provider key actually authenticates via a freemodels.listcall (no model generation, no token spend), reporting per-provider OK/FAIL with latency.primr keys test <provider>checks one. Complementsprimr doctor, which deliberately never makes a live model call. Backed by a newProvider.validate_credentials()seam implemented for Gemini, the OpenAI-compatible providers (OpenAI/xAI/Ollama), and Anthropic..env.example/.envcover every recognized key, including the OpenAI-compatible endpoint seam (LOCAL_LLM_BASE_URL/LOCAL_LLM_API_KEY) for local servers or an Azure Foundry / Bedrock gateway, plus current model-override guidance.- Full observed-stack grounding for the AI strategy. Recon context now leads
with an "Observed Vendor Stack the Strategy Must Address" rollup naming the
detected identity, cloud, AI-provider, and key SaaS ecosystems, so the strategy
addresses the whole stack (for example Microsoft 365 + Okta + AWS/Azure +
Anthropic/Claude) rather than only the email or primary cloud provider. AI
detection now covers agent frameworks and LLM tooling (n8n, Dify, AutoGen,
CrewAI, LangSmith, MCP endpoints) in addition to model providers, identity
providers are surfaced even without an auth type, and the standalone strategy
path attaches a co-located
_recon_context.txtwhen present. - AI Strategy prompt v2.2.0 preserves a complete opportunity inventory separate from the prioritized portfolio, adds a portfolio hierarchy and transparent prioritization, translates recent AI developments into company-specific ideas with explicit pattern-maturity labels, and strengthens the no-fabrication evidence rules (unknown baselines, ownership, and value are named rather than invented).
Fixed¶
primr --analyze-reportno longer misgrades a Strategic Overview as an AI Strategy. Report-type detection previously keyed on the substring "ai strategy" appearing anywhere in the body, so a 23-section Strategic Overview that merely discussed a company's AI strategy was graded against the wrong template (and penalized for missing sections it should not have). Detection now uses the filename first, then a section-structure fingerprint. The primr-zeroreport-contract.mdnow documents the exact citation format the QA gate expects (inline[cite: N]markers + a## Sourcesappendix) with a worked example, so a contract-compliant report also passes the gate.- Approved execution preflight now validates Gemini access through model metadata instead of generating a throwaway response. Cost estimates and approval boundaries therefore cover every model-generation call.
- Successful scrape-only runs now persist explicit
not_requestedstrategy and vendor-refresh outcomes. Batch research reads the same canonical outcome state as single-company execution, preserves a completed base report on partial fulfillment, and returns nonzero when requested work is incomplete or cannot be verified. - Batch resume now skips an existing base report only when its stable hash is bound to a canonically completed run whose mode, URL, strategy targets, and refresh targets exactly match the new request. Partial, changed, and outcome-free artifacts require a fresh estimate instead of silently becoming successful on the next invocation.
- The active
skillsstrategy now reaches its existing generic generator from integrated runs and is included in Deep Research budget accounting. Its per-role skill artifacts remain part of the generated deliverable. - Scraper tier-escalation tests now isolate URL-safety approval from DNS, so a local resolver outage cannot turn a deterministic unit test into a CI failure while dedicated SSRF tests continue to cover the security boundary.
- Generated Primr Zero host workflows now point to the bundled skill and its
full report contract, and distinguish
$0Primr model spend from host billing or plan limits that Primr cannot verify. - Standalone
--ai-strategy-only --jsonnow separates zero-call estimates, approval-required refusals, and execution results into versioned one-object contracts. Successful and partial results name every expected target and preserve successful artifact paths; provider exceptions stay body-safe and return nonzero without contaminating machine stdout. - Local job monitoring now accepts fulfillment state only when the run
lifecycle and both persisted outcome partitions are canonical. Missing,
unknown, or internally inconsistent state reports
unknowninstead of a false completed result. - Fast multi-platform refresh budget checks now include every earlier refresh that reached provider submission. A later target cannot pass its incremental budget gate using the stale end-of-loop task count.
- Vendor research usage now records a conservative submitted-task row when the provider call or polling path raises. Preflight failures remain unrecorded, and publication failures remain single-counted.
- Integrated research now distinguishes successful base-report publication from strategy and explicit vendor-refresh fulfillment. Run state and JSON list expected, completed, failed, and budget-skipped targets; partial results preserve successful artifact paths but return a nonzero CLI status. The standalone multi-platform strategy command likewise requires every requested target to succeed.
- Research JSON now handles binary DOCX primary artifacts without attempting a
text decode. It preserves base-artifact
statusand adds an aggregatefulfillment_status; missing or inconsistent outcome state fails closed asunknownwith a nonzero exit instead of being accepted as success. - Human completion output and local job monitoring now show partial strategy or refresh targets, unresolved work, and the exact run-state path. Completed base reports remain available with focused dry-run guidance for retrying only the unresolved work.
- AI Strategy Deep Research accounting now uses run-local submission callbacks across standard and deep routes. Concurrent runs cannot claim one another's tasks, preflight failures are not priced as submitted work, and optional standard-strategy setup failures preserve the base report while persisting a failed strategy outcome.
- Vendor-refresh accounting now uses run-local provider callbacks rather than process-global counter deltas. Concurrent jobs cannot claim each other's refresh tasks, budget checks use only the current run's submitted work, and a cached fallback no longer hides a failed explicit refresh.
- Standard-mode actual-cost and usage summaries now include its AI Strategy Deep Research task and every explicit refresh task that reached submission. Refresh tasks remain excluded from the main usage row because their own durable usage records already carry that cost.
- Local preflight checks now run before the cost gate, while network
connectivity checks wait until after budget acceptance. A run refused by
--budgetperforms no provider connectivity request, and active budget state is cleared even when activation or network preflight raises. - Machine-readable research and direct vendor commands now keep stdout to one JSON object on configuration, preflight, provider-failure, partial-result, and success paths. Provider progress and optional cache failures cannot contaminate the JSON channel.
- Lite, standard, and asynchronous AI Strategy paths now consume vendor and cross-industry context through one bounded private-snapshot seam. Symbolic links, hard links, oversized inputs, and files that mutate during validation are rejected before provider egress, and snapshots are removed after success or failure.
- Deep-research contract tests no longer perform an accidental live hiring-data lookup, reducing the 20-test group from timeout-scale latency to a few seconds and keeping local validation network-independent.
- Fast AI Strategy generation now includes the same existing cached cross-industry research used by standard and standalone strategy paths, including for vendor-neutral runs. The cache is never generated or refreshed by this lookup, reads stay bounded, linked or unstable files are rejected, and cache failures remain visible without exposing local paths or blocking strategy generation.
--refresh-vendor-researchnow reaches both fast and standard AI Strategy execution, including vendor-neutral strategy runs. Dry-run, interactive, and budget estimates conservatively quote each requested refresh as a separate Deep Research task before execution.- Estimate-bound CLI and MCP strategy paths now reuse cached vendor research without honoring ambient automatic-refresh configuration. Optional cache lookup and read failures remain body-safe and no longer block fast strategy generation; an unsuccessful vendor-neutral refresh falls back to the existing cached cross-industry context when available.
- Vendor-research publication now uses symlink-safe atomic replacement and an atomic writability probe. Provider-task usage is recorded before local cache publication, publication failures expose only their stable failure type, and a failed refresh reuses an existing cache with an explicit warning.
- Multi-platform fast refreshes now resolve serially before parallel strategy writing, preventing shared provider-client and usage-tracker races. Fast refresh preflight requires both the fast-runtime key and the Deep Research key before the base pipeline starts.
- Dry-run now auto-selects the fast cost shape only when execution would select it. Non-XAI provider configuration keeps its routed standard estimate instead of receiving a fast estimate that execution cannot follow.
- The legacy non-fast
structuredruntime now rejects custom strategy types or multiple explicit platforms before preflight instead of silently producing a different or incomplete strategy set. Its estimates use the single platform that runtime supports. - Direct
--generate-vendor-researchruns now quote an aggregate estimate, support zero-call dry-run and budget enforcement, require confirmation unless--skip-confirmexplicitly approves noninteractive execution, and provide one-object JSON estimates and results. Partial or total generation failure returns nonzero without hiding successful artifact paths, andallincludes the private accelerated-infrastructure target.
[1.36.1] - 2026-07-18¶
Changed¶
primr update,primr upgrade, andprimr self-updatenow share one strict argument contract. Unknown or positional arguments fail before update logic, scoped help remains side-effect free, and non-interactive installs require explicit--yesapproval.- Early research and dry-run validation failures now emit one
primr.command-error.v1object in JSON mode, including actionable hints when available, instead of mixing human console lines with machine output. Workspace lease, interrupt, and unexpected top-level failures use the same contract, including in verbose mode. - Standalone and MCP strategy generation now validate report identity and content together, copy only a stable private snapshot into provider context, reject linked or multiply named files, and fail closed if the source changes.
- MCP approval tokens are now single-use and bound to the issuing process instance. A restart requires a new estimate and fresh approval even when the signing secret is shared.
- HTTP mode now separates shallow
/healthzliveness from body-safe/readyzreadiness. Controller activation requires the journal lease, strict journal reload, a secure audit-sink check, and atomic persistence preflight. Runtime journal and required worker-artifact failures close readiness, and failed journal writes roll memory back to durable state. - Azure templates run one persistent controller replica, use a single active
revision, route readiness probes to
/readyz, and avoid fixed regional price claims in deployment guidance. - README and roadmap claims now match the selectable strategy catalog, confidence-label vocabulary, community files, and shipped public docs.
Fixed¶
- The placeholder-strategy regression test now exercises a synthetic strategy directory and proves that active definitions are discovered while placeholders are excluded.
- Controller startup now rejects linked journal parents and linked or multiply named journal and lease files before mutation. Journal writes use randomized atomic temporary files, strict reloads happen only after lease acquisition and persistence preflight, and failed writes restore the last durable in-memory snapshot.
- macOS controller state validation now accepts the operating system's
root-owned
/varand/tmpaliases while continuing to reject redirected paths that are not the standard protected aliases. - Audit append continuity now pins the preflight identity and size, so file replacement or truncation cannot be laundered by a later successful append. Required worker directory, log, and terminal-manifest failures also close readiness, including cleanup failures.
- Scrape traces are now bound to the owning job identifier and use collision-resistant filenames. Overlapping same-company runs can no longer attach another job's trace to their artifact inventory.
- Stdio transport task failures now propagate to the shared controller lifecycle instead of becoming unobserved task exceptions.
- Azure validation now checks native CLI exit codes directly, avoids dynamic command evaluation, and treats a missing Container App FQDN as a failed smoke test unless the operator explicitly skips smoke validation.
- Batch error-path tests now isolate the runtime output root, preventing local same-day reports from changing regression-test behavior.
[1.36.0] - 2026-07-18¶
Changed¶
- The default AI Strategy now uses one canonical business-first contract across the fast, standard, async, and MCP-compatible prompt paths. It begins with company economics, an enterprise performance agenda, strategic tensions, industry direction, art of the possible, and ranked value pools before technology. Defend, improve, extend, and create choices tie initiatives to measurable revenue, efficiency, product, service, and risk outcomes. Initiative decision cards now require accountable owners, evidence, non-AI alternatives, opportunity cost, fully loaded unit economics, tests, controls, kill criteria, and revisit triggers. A disposition ledger accounts for every material observed ecosystem. The architecture section evaluates the complete observed stack plus public, multicloud, private, on-premises accelerated, edge, and hybrid placement only when workload requirements and lifecycle economics justify them.
- Batch research and enrichment now have separate estimate-first execution
contracts. Research gates
--budgetagainst the whole pending batch, requires websites up front, defers local-only preflight until after approval, and never automatically retries paid rows. Enrichment quotes only missing-site lookups, pins the quoted model, disables retries and provider failover, and clears its runtime budget. JSON dry-runs emit one object on success and handler errors. - Standalone
--ai-strategy-onlynow supports a zero-call--dry-run, emits the same cost and time plan before execution, and requires approval unless--skip-confirmis explicit. Strategy context now retains a normal full Strategic Overview up to a 200,000-character deterministic bound. - Default platform selection now produces one integrated strategy: agnostic when recon has no strong infrastructure signal, the detected ecosystem when there is one strong signal, and vendor-neutral integration when several ecosystems are detected. Explicit multi-platform commands still fan out. DNS-derived context now states its evidence limits instead of claiming an active contract, production adoption, primary platform, maturity, or spend. The default xAI plus Gemini estimate is therefore about $0.89 and 34-53 minutes; explicit two-platform fan-out remains about $1.01 and 37-59 minutes.
- Standard AI Strategy evidence assembly now bundles bounded recon and hiring artifacts when present, in addition to the Strategic Overview, insights, gap analysis, workbook, and discovery notes. Deep Research also retains supplied context files. Strategy-specific epistemic and formatting rules are applied by the composer. Current product claims require official evidence or an explicit evidence gap, and shipped AI YAML no longer pins dated catalogs.
- Strategy reports no longer receive a generated-by attribution line. Operator discovery notes are described as perspective-bearing evidence and remain sanitized before prompt composition.
primr doctornow treats a valid no-key installation as ready with warnings: keyless prep and recon remain available while provider-backed research is marked unavailable. Its default connectivity check no longer sends a model generation request. Root help and local-state output now distinguish completed provider-job finalization (--resume-latest) from local run continuation (--resume-local).- MCP and A2A doctor output now preserves its legacy fields while adding the
advertised overall
status, componentchecks, and a body-free audit-sink projection. Recent audit reads use a capped tail rather than loading the entire retained JSONL, report malformed complete events, and distinguish an unobserved sink from read/write degradation without exposing paths, event bodies, URLs, caller ids, or exception messages. - Cloud health failures now affect the overall MCP and A2A doctor status, live health response bodies are not echoed, and A2A operational logs record only known skill labels and message lengths. Audit labels are allowlisted or normalized, encoded events are size-capped, and recent reads reject invalid event envelopes and additive fields. Audit file access rejects symbolic-link targets, and health reports replacement or truncation after a successful write. Invalid, non-finite, or negative cloud cost limits now degrade health instead of emitting non-standard JSON values.
- Root
primr --helpis now a concise, workflow-first surface covering Primr Zero, provider-backed estimation, recovery, and keyless commands; the full argparse reference remains available throughprimr --help-all. Console andpython -m primrexecution now share a lightweight entry path, so version, root help, and focused init/doctor help do not load the operational CLI or initialize workspace directories. Public examples use placeholder organizations only. primr prep --helpnow describes the host capability and existing-plan boundary without coupling the command to a vendor roster.primr prepnow reportspartialcollection honestly, carries bounded coverage warnings from the evidence manifest, lists the source index and host workflow alongside the evidence packet, and prints one explicit host handoff action.primr prepnow publishes a bundle only after assembling its complete manifest in private same-root staging. Collection errors and interrupts leave no discoverable partial directory, artifact scans ignore active prep staging, and--install-skill ... --dry-runpreviews the destination without network access or file writes.primr prepnow enters through the lightweight console and module path, avoiding the provider-backed CLI import graph for keyless preview and collection. Collection and skill-install interruption return exit code 130 with recovery guidance, and dry-run help now covers both collection and skill installation.- Primr Zero host workflows now fence target metadata as untrusted data, use
the canonical Confirmed, Reported, Estimated, and Hypothesis vocabulary,
checkpoint the Markdown report inside the prep bundle, and confirm its
primary_reportinventory role before passing an exact path to a requested downstream workflow when local execution is available. - Cloud doctor output now distinguishes a live health probe from configuration
presence. Unprobed cloud dependencies report
configured, include an explicitprobe_performed: false, and omit endpoint, account, and connection values. - pipx is now the default installation path in the README. Convenience installers use a download, inspect, then execute flow rather than piping a mutable remote branch directly into a shell, and their completion guidance separates the keyless agent-host path from provider setup and spend approval.
- Agent hosts now treat a bare
primr "Company" URLrequest as Primr Zero by default and keepprimr prepas internal plumbing. Only explicit paid, metered, provider-backed, premium, budget, provider-key, or provider-only modifier intent selects the billable pipeline; configured keys alone are not spend consent. Repository-local launch guidance and no-shell research fallback make the same request usable across prepared coding workspaces and research hosts without changing direct terminal CLI behavior. - Default research dry-run and cost-estimate labels now use the product CLI
mode name
full(for examplefull (Grok 4.3 hybrid)), matching--mode fulland root help instead of the internal "standard" path name. primr --list-recentnow groups primary report deliverables separately from calibration, QA, and verification diagnostics, prints root-relative paths so same-named files are distinguishable, and labels each row with a short type tag. Within Deliverables, named product reports rank above empty or incidental files while preserving newest-first order inside each rank. Root help epilog leads with the first-run lifecycle (initthrough--list-recent) and includesprimr skills.
Added¶
- Fresh source checkouts now include synchronized
.claude/skills/primrand.claude/skills/primr-zeroproject skills while local Claude settings remain ignored. Mirror checks cover the project, plugin, and packaged copies. - Artifact inventory schema 1.1 adds a content-free
artifact_roleto the existing local and MCP metadata seam. Agents can select the primary overview, relevant strategy modules, other reports, diagnostics, and run metadata for downstream document workflows without reading bodies or assuming a specific audience, brand, renderer, or output format. The zero-spend host workflow now carries the same explicit-path handoff contract. - Added an explicit, single-company experimental gate for the unpromoted Codex
fast.source_relevanceroute.--inference hybridstill uses cloud by default; host execution additionally requires--acknowledge-host-agent-may-bill, records potentially metered billing and pending-eval status in route metadata, and rejects host eligibility without a recorded acknowledgment. Hybrid retains the already-estimated cloud baseline when no runner qualifies; a selected host failure keeps all sources without a second cloud call. Dry-run text and JSON disclose that host charges are unknown, excluded from the estimate, and outside--budget. Batch fan-out is rejected. - Added a graph-backed architecture cohesion plan and deterministic fitness gates for first-party import cycles, empty source modules, and unexplained sub-40-line modules. Package re-export edges are part of the cycle baseline, while reviewed security, policy, lifecycle, adapter, protocol, and composition boundaries remain explicitly permitted.
- Cloud-vs-local calibration comparisons now preserve each disagreement as a
body-free pointer in the raw report-bound sidecar. Its zero-based claim index
resolves into the sidecar's top-level
claimsarray for human adjudication, while compact MCP and A2A summaries continue to omit disagreement details and raw claim or source content. - Added weekly manual-triggerable dependency auditing with locked
pip-auditcoverage for every shipped extra and a pinned Trivy filesystem scan. - Added lock-derived, hash-complete build and runtime dependency manifests for both production Dockerfiles. Container builds now install the local wheel without resolving a second dependency graph, and CI builds and smoke-tests both production image surfaces from their documented build contexts.
Fixed¶
- Standalone strategy recovery now hashes a stable report descriptor during validation and verifies the private snapshot digest before any model call. Same-inode, same-size replacements with a restored timestamp fail closed, as do linked files, paths outside the fixed report roots, and reports changed during copying.
- Run workspaces now use atomic sortable allocation and cross-process ownership leases. Completed and canceled resume behavior is explicit, dead-owner recovery is bounded and fail-closed, and publication locking covers CLI, async API, and MCP strategy paths so concurrent runs cannot overwrite shared artifacts. MCP strategy outputs remain job-local.
- Deep Research now prevents duplicate live interactions, and lite strategy generation uses the exact selected model with a 10,000-token output ceiling across supported direct and failover routes.
-
Website-only legacy CSV rows are preserved by deriving a validated display name from the normalized hostname. Unsupported batch and enrichment options now fail visibly instead of being ignored, including the correct
--questionoption label and host-billing acknowledgment. -
Clean wheel and source-distribution builds no longer emit false missing-file warnings for local caches, outputs, logs, working data, or platform metadata. Release inventory checks continue to reject development state and generated artifacts.
-
Recovered MD/TXT/DOCX deliverables now render and verify in a same-filesystem staging directory before any canonical path is promoted. In-process promotion failures remove new files and restore pre-existing outputs; an incomplete rollback preserves staged backups visibly for diagnosis. Fallback TXT writes are atomic and a fallback failure no longer aborts later pending jobs.
- Provider recovery now fails visibly when the pending-job registry cannot be read or contains a non-object job entry, restores prior artifacts after an in-process interruption, rejects symbolic-link artifacts, and derives contained collision-resistant filenames from provider interaction ids.
primr --clear-jobsno longer calls every pending recovery record stale or overwrites the registry directly. It requires confirmation unless--yesis supplied, removes only the previewed records under the canonical lock and atomic write seam, preserves concurrently added records, and returns a visible failure when persistence cannot be updated. Registry mutations now hold an operating-system lock across the full read-modify-write transaction, so separate Primr processes cannot overwrite one another, and malformed UTF-8 fails visibly during cleanup.- Primr Zero no longer stalls when the CLI launcher is unavailable or the user declines installation. Research-capable hosts continue through the native report contract, disclose unavailable Primr collectors, and never switch to billable execution silently.
- Security operations guidance now identifies the REST key manager as a process-local development scaffold, documents bounded admin-only audit inspection, uses the actual MCP audit JSONL path, preserves active logs while shipping temporary snapshots, and matches the repository's hard CI security gates. Staging and load guidance now exercises the production MCP or A2A protocol with bearer scopes and non-billable tools instead of the unimplemented REST submission route.
- Primr operator guidance now intercepts requests for a free version, no API
spend, or use of an existing agent plan before billable mode selection. It
routes to
primr-zero, falls back inline to keylessprimr prepwhen the dedicated skill is missing or stale, and explicitly prevents the billable--mode scrapepath from being presented as the free option. The Claude plugin manifest is synchronized with the package version so hosts can detect updated skill instructions, and the operator skill frontmatter is valid YAML for strict host loaders. - Raised the MCP dependency floor and lock to 1.28.1, which contains the fix for CVE-2026-59950; the locked dependency audit is clean again.
- Root-help release integrity now compares parsed command examples, so added explanatory help lines cannot be mistaken for executable launch commands.
- Skill-pack executable-instruction admission now rejects leading environment assignments, dynamic shell command words, additional Windows executable types, persistence through login profiles, CPython and indirect interpreter sinks, CMD comment variants, and executable directives hidden after ECMAScript regex literals. Sensitive-data policy also treats stacked negations and transformed ciphertext or Base64 transfers as affirmative exfiltration instead of safe prose.
- Behavioral-evaluation runtime estimates now reserve the bounded retry wait as well as call time. OpenAI-compatible transports disable automatic redirects alongside SDK retries so the declared attempt cap also bounds physical HTTP requests, and authored HTTP targets with malformed or out-of-range ports fail closed.
- Split three newly expanded skill-pack security modules at cohesive trust boundaries: language-aware comment projection, execution dataflow, and the existing verifier-asset registry. Every resulting module is below the approximate 800-line review threshold without compatibility shims or circular dependencies. All eight touched trust-boundary modules now sit in the enforced mypy annotation-completeness allowlist.
- Reduced first-party import-cycle components from four to two without adding a source module. Gemini resource cleanup no longer imports its high-blast deep-research consumer, model defaults now live in the dependency-leaf registry, configuration errors share an existing stdlib-only leaf, and URL security imports its concrete submodule instead of cycling through the package facade. Fresh-interpreter tests verify both import orders against the local source tree. The empty, unused scraping compatibility module was removed.
- Saved skill-pack plans now pass one bounded, strict admission boundary before estimation or execution. CLI and MCP approval tokens bind the canonical curated roster, exact saved-plan content, refinement depth, role controls, evidence shape, and remote-icon choice, while execution consumes the same in-memory snapshot instead of rereading mutable input. Cost estimates now reserve the full refinement and pack-level reconciliation ceilings, count the effective roster exactly, and reject non-finite prices.
- Pack-level overlap repair now resolves at most ten distinct canonical skill pairs, deduplicates aliases, and preserves stable skill identity across sequential repairs. Failed authoring and saved-plan validation diagnostics no longer reflect untrusted role names or malformed values.
- Company names that cannot be represented portably as filesystem components are rejected before research begins, including Windows-reserved characters, device aliases, and the current-directory component. Legitimate trailing punctuation remains available for report titles but is normalized in path components. Temporary research context files also release their raw descriptor before they are consumed, preventing Windows handle leaks and nondeterministic cleanup failures.
- URL-derived domains and artifact names now use canonical hostnames instead of
raw authorities. Explicit ports and credentials no longer leak into working
directory names, search exclusions, hiring probes, citations, scrape
artifacts, or low-value URL checks. IDNA 2008 conversion keeps distinct
internationalized domains from colliding, invalid ports fail closed, and only
a leading
www.label is removed. - DuckDuckGo own-site filtering now respects DNS label boundaries, so a target
such as
acme.comexcludes its real subdomains without discarding unrelated domains such asnotacme.com. Google site exclusions and validated external source filtering now remain correct when the configured website has an explicit port. External-source allowlists preserve a deliberately narrowwwwscope, and remembered rate-limit state uses the same canonical host key when a site runs on a custom port. - Calibration sidecars now bind to the exact report bytes they evaluated. Pack manifests and compact MCP/A2A calibration summaries reject legacy, missing, or stale report bindings instead of presenting unrelated evidence. Manifest report and sidecar metadata is parsed, validated, fingerprinted, and embedded from one byte snapshot so concurrent file changes fail later integrity inspection instead of creating internally inconsistent evidence.
- Production recovery now executes built-in same-call and backoff retries, records only actions actually attempted, and exposes deterministic sleep injection for tests. Recovery telemetry listener failures no longer discard successful retry results, and route plus resilience state updates now share a per-run serialized read-modify-write transaction so concurrent workers cannot overwrite one another's events.
- A2A interruptions after durable job creation can no longer strand an active
job. Cancellation before supervisor ownership records
CANCELLED; an interrupted supervisor startup preserves its authoritative cleanup result or recordsFAILEDwhen ownership never completed. - Local artifact and heartbeat overwrites now tolerate bounded, transient Windows sharing violations while preserving atomic replacement, prior data, and temp-file cleanup on persistent failure.
- The standalone security scanner now produces Windows-safe output, inspects
executable syntax instead of matching comments and strings, detects genuine
text-mode encoding omissions, and uses the canonical
pip-auditCI gate. The ten real encoding omissions it identified now use explicit UTF-8.
Security¶
- Behavioral-evaluation JSON is no longer an unchecked agent-instruction
carrier. Generated cases are bounded and screened before any with-skill,
baseline, or grader call; grader inputs are nonce-fenced; and packaged eval
files require a bounded form of Anthropic's current
expectationsschema with unique keys and identifiers. The optionalfileskey is recognized only when empty because Primr does not yet package eval input assets; nonempty references fail closed instead of becoming dangling paths. Primr's earlierassertionsform remains readable. Unsafe and default-ignorable Unicode, control-plane overrides, affirmative credential exfiltration, executable launch directions, alternate eval files, oversized payloads, and cross-skill name mismatches fail closed without blocking fenced code-review data or explicit prohibitions and descriptive security-review tasks. Zero-case requests make no provider call. Packaging validates the admitted file set once before writing either artifact format. Fenced input is admitted only behind a strict review-only frame, and execution intent before or after the block fails closed. Images, active or local link destinations, executable paths, common imperative frames, sensitive credential reads or transfers, and the complete Unicode 17 default-ignorable set are covered both raw and after bounded recursive CommonMark entity, percent, and Unicode compatibility decoding; residual encoded layers fail closed. Clause-level negation and exception handling separates inert security review from later credential access or transfer. Markdown links and definitions fail closed because their hidden destinations are unnecessary for eval artifacts. Review-fenced examples retain their inert code-review use case while fence metadata, embedded prompt control, and unsafe comment prose are checked. CommonMark canonicalization and link policy now have one typed shared seam; eval schema and control-plane policy share a focused validator. Task arms and both graders run statelessly so case-generation context cannot leak into the baseline, while retaining the caller's configured model and reasoning tier. Behavioral-eval approval now prices the actual one generation plus four calls per case from the model registry, reserves every output ceiling and bounded input budget, includes sequential runtime, and uses the same strict two-attempt cap as execution. OpenAI-compatible SDK retries are disabled so the explicit Primr loop is the sole retry owner; a transport-level regression proves that two approved attempts issue exactly two HTTP requests. Credential screening now covers response-oriented disclosure, common token and credential-file forms, and chained metadata-to-value transfers without rejecting metadata-only governance reporting. Adjacent-clause pronouns and output synonyms cannot detach raw values from their credential antecedent. Execution screening now covers structural terminal and console entry, interpreter data sinks, downloaded-result coreference, boot, and click activation while preserving ordinary alphanumeric business tasks and non-executable downloaded-data use. Language-aware fence scanners inspect inline comments, including ECMAScript template interpolations and native CMDREMforms, without treating quoted comment markers or template text as instructions. Bounded instruction grammar also covers transformed-secret transfer, persistence destinations, downloaded executable activation, and interpreter evaluation while retaining explicit prohibitions and metadata-only credential inventories. Raw HTTP targets that are malformed, lexically local, private, reserved, or cloud metadata endpoints fail closed without a DNS side effect, including targets followed by prose delimiters. Mixed-script and same-script command confusables are checked without rejecting pure Greek, Cyrillic, Armenian, or accented-Latin prose. Skills with no valid generated cases are skipped instead of being reported as benchmarked. - Saved plans reject oversized files, amplified prompts, malformed structures, nonportable roles, and rosters above the global cap before provider work. Operator curation is atomic and cannot silently discard approved operator roles. Approval tokens are content-bound, so same-sized plan substitutions or post-estimate curation changes fail closed.
- Skill-pack authoring now accepts only markdown references from model-proposed
companions and applies a CommonMark-aware structural executable-payload
boundary across agent-consumed fields: fenced and indented code blocks,
including container-nested, table-cell, entity-encoded, and mixed-whitespace
forms, raw HTML except the verifier's literal artifact placeholder, plus
multiline program syntax, direct or determiner-wrapped executable commands,
common instruction-prefix variants, operational YAML/JSON keys, non-empty
argument vectors, and correlated process file and argument specifications,
helper-materialization directions, and unregistered executable references
fail closed. Link destinations, titles, and used or unused CommonMark
reference definitions are decoded before inspection. Multiline code and
embedded JSON reconstruction have explicit work and size bounds. YAML
aliases, anchors, explicit tags, token overflows, and input overflows fail
closed before safe basic-value loading. Role
metadata is covered, and generated SKILL.md frontmatter uses
control-normalized JSON/YAML scalars with an exact parsed-structure round trip.
Recon, hiring, industry, role, and citation evidence is sanitized and
nonce-fenced before authoring, and the final rejection boundary uses the
shared detector's high-confidence authored-output policy. Invalid role names
fail before a provider call. Scalar process
specifications, Ruby and Perl command placements, executable output-format
directives, and verifier paths outside the canonical workflow are rejected.
Ordinary workflow prose such as
Start with an intake stepandCall the Salesforce APIremains valid. This boundary is defense in depth and deliberately makes no claim to infer the intent of arbitrary prose. Pack reports require review before installation and retain host tool allowlists, approval gates, and sandboxing as trust boundaries. The packager admits executable bytes only at the registered first-party path, on the one verifier skill, with its canonical invocation. The verifier rejects absolute, UNC, device, traversal, alternate-stream, symlink, and junction paths before open, then uses a nonblocking bounded regular-file reader with strict UTF-8 and content-safe errors that do not reflect untrusted paths or bytes. Companion and collision paths reject Windows device basenames and overlong components. Distinct companies whose names sanitize to one output token receive deterministic collision suffixes while same-company reruns preserve identity. Same-day packaging now stages a complete tree before replacing only marker-owned or narrowly recognized legacy output; links, mounts, and unrelated directories are refused, Windows renames retry, and exhausted post-commit cleanup is reported without mislabeling a published pack as failed. - Raised Pillow to 12.3.0, closing the five advisories affecting the previous 12.2.0 lock, and added a dependency-floor regression gate.
- JWT verification now preserves explicit empty scopes instead of granting legacy defaults, rejects malformed scope claims, and fails closed on boolean, non-finite, or exactly expired time claims. Age-limited static admin tokens no longer bypass rotation through the token cache, and non-finite admin-token max-age configuration is rejected or ignored safely.
- MCP HTTP refuses unauthenticated non-loopback listeners even when plaintext is explicitly acknowledged, preventing a development switch from becoming remote anonymous access.
[1.35.2] - 2026-07-12¶
Fixed¶
- Removed the remaining MCP and A2A server import cycles through a shared cross-transport controller contract. Direct strategy generation uses a focused shared operation instead of routing through the research pipeline module.
- Added architecture and fresh-interpreter import-order gates that prevent concrete server dependencies from returning outside composition roots.
- Standalone strategy requests now dispatch the requested YAML-defined module instead of relabeling an AI strategy artifact as another strategy type. The legacy skills strategy preserves its documented per-role skill artifacts.
- Added managed-identity construction to the Azure Cosmos and Blob stores used by the reconciliation function. Corrected the vertical-slice cache argument, curly-quote extraction, non-finite audit parsing, negative QA retry counts, and standalone process exits.
- Removed the unused plural platform compatibility global; tests now exercise the canonical normalization seam directly.
- Synchronized operator skills and API, architecture, configuration, security,
and internals docs with the live recon, hypothesis-memory, roadmap-band,
hook, subagent, model, legacy config-schema default, and provider-fallback
contracts. Roadmap blocker queries now accept current bands such as
1.x.
Security¶
- Pinned every remote GitHub Action to an immutable commit and every shipped Python container base to a verified multi-platform digest. Added fitness tests so moving tags cannot silently return.
- Standalone strategy estimates and approval tokens now use Primr's canonical Deep Research planning cost instead of legacy sub-dollar placeholders. Standalone strategy and vendor-research usage are persisted, and cost-gated AI strategy execution cannot trigger an additional environment-driven vendor refresh.
[1.35.1] - 2026-07-12¶
Added¶
- Added a packaged, versioned worker protocol and one-process-per-job supervisor shared by local MCP and A2A research. Parent-owned progress, ownership-ready startup, POSIX process groups, Windows kill-on-close Job Objects, restart reconciliation, and worker-exit manifests for supervised failure or cancellation make the lifecycle enforceable without moving research logic out of Python.
- Added an OS-backed exclusive controller lease shared by MCP, co-hosted A2A, and standalone A2A. Restart reconciliation now happens only after lease acquisition, and the final lifecycle owner releases the lease only after all retained workers are reaped.
- Split worker environment, process control, protocol, terminal policy, manifest, lifecycle-record, validation, A2A cancellation, and A2A event concerns into focused modules reflected in the architecture graph.
Fixed¶
- Cancellation now becomes terminal only after the owned worker exits, repeated cancellation is idempotent, terminal states cannot be rewritten by late updates, A2A reports cancellation instead of failure, and admin cancellation follows the documented authorization policy without leaking job existence to other callers. Only cooperative exit 130, POSIX termination signals, and known Windows control or forced-termination outcomes qualify as cancellation; unrelated nonzero exits remain failures.
- MCP full and premium execution now deliver the default agnostic AI Strategy
priced by the estimate unless
no_ai_strategy=true. The standard orchestrator path no longer omits that promised artifact, and successful job completion is committed only after its manifest is atomically written. - Integrated MCP estimates and execution now share one explicit contract: one
AI strategy target per research job. Platform fan-out, the multi-target
msalias, plural execution platforms, and non-AI integrated strategies fail before approval or job creation; standalone strategy tools remain available for additional documents. - Worker snapshots now receive full schema, type, range, sequence, and job validation. Canonical stage, heartbeat, and completion timestamps are owned by the parent observation clock rather than accepted from the child.
- Graceful controller shutdown now finishes the bounded worker stop and reap sequence before releasing its journal lease. An unreaped worker is a loud shutdown failure that retains the lease and cannot be mistaken for a clean restart boundary.
- A controller reloads journal state after acquiring its exclusive lease, so a server object created while another controller is active cannot reconcile a stale snapshot over newer terminal state. Descendant-tree cleanup must also succeed before the worker handle is released; cleanup failure is retried and retains controller ownership.
- A2A health and QA operations now depend on focused transport-neutral modules, keeping the A2A and MCP startup graph acyclic. Worker log streams are owned by the spawn scope and closed immediately after safe subprocess handoff.
Security¶
- Supervised workers now receive a least-privilege research-provider and
runtime environment. Controller, cloud-identity, telemetry, and CI secrets
are removed and blocked from supervised
.envrestoration. Supervised files are parsed without interpolation, and interpolation-bearing assignments are rejected so blocked values cannot flow into allowed provider variables. - Control and event pipes become private, non-inheritable descriptors before pipeline imports, while ordinary stdin and stdout are redirected away from the protocol. Linux uses parent-death signaling during bootstrap, then a private-pipe EOF watchdog that kills the worker process group on controller loss. The POSIX path remains explicitly best effort for a native GIL stall or a descendant that deliberately escapes the process group.
- Local implicit authority is now bound to the actual unauthenticated stdio transport. JWT subjects matching reserved local identities are rejected, and missing versus cross-tenant jobs, cancellation targets, resource reads, and active-job collisions use indistinguishable responses.
- Local no-auth A2A authority is represented by an internal marker available
only on loopback listeners. Authenticated reserved subjects cannot claim it,
report resources are limited to locally owned A2A jobs, and
tasks/getrequires the exact SDK request owner while hiding cross-owner task ids like missing ids.
Documentation¶
- Defined Primr's measured runtime policy: Python-first rather than Python-only, supervised per-job processes for truthful cancellation, optional Rust acceleration behind differential and end-to-end gates, and explicit evidence triggers for Go and Mojo/MAX.
- Reconciled concurrency guidance with the live homepage and ten-page pilot, bounded three-worker corpus path, per-host limiter, async bridge, shared-state constraints, and the fact that cancelling a coroutine does not terminate a running thread.
- Clarified that every user-operated OpenAI-compatible model server follows the same hard-zero, busy-capacity, quality, privacy, and retry contract.
[1.35.0] - 2026-07-11¶
Added¶
- Added
primr prep, a hard-zero evidence collection and host handoff path, plus a wheel-packagedprimr-zeroAgent Skill for Codex, Claude Code, Copilot, Gemini CLI, Cowork-style file handoffs, and other capable hosts. - Prep bundles now include stable source IDs, typed fallback provenance,
prompt-injection-fenced and size-bounded evidence, hashes, a portable skill,
and a manifest that records zero model calls and
$0.00API spend. - Local OpenAI-compatible capacity now reports
available,busy, orunavailablewith bounded machine-readable retry guidance. Actual chat failures emit the same structured busy contract after short in-call retries.
Fixed¶
- Explicit local inference routing no longer returns a paid legacy cloud model when no local backend qualifies.
- Local route ledgers now distinguish adapter gaps from capacity failures and preserve safe busy retry metadata through summarization, source relevance, both hiring-signal model calls, and the fast/deep hiring wrapper.
- Internal host-agent billing now defaults to unknown, capability routing
rejects unverified host billing, and the Codex subprocess refuses to run
until a caller supplies an explicit billing policy. The public inference
profiles remain
cloudandhybrid. - Roadmap API and MCP roadmap resources now parse the real
1.x,2.0, and3.0version bands, stop at later non-version sections, and expose the intended dependency order instead of attaching the Active Queue to3.0.
Documentation¶
- Refreshed the architecture package map and fast-stage inventory to match the current source tree and completed orchestrator extraction, with a fitness test that requires every top-level package to remain represented.
- Refreshed the next-steps guidance with the shipped durable background-job lifecycle and the verified Trusted Publishing release contract.
[1.34.50] - 2026-07-10¶
Added¶
- A versioned, body-free
primr.job-statusv1.0 contract now normalizes job lifecycle, progress, timestamps, artifact availability, and observation errors across CLI, MCP, A2A, hosted, and application API status surfaces. primr --list-recent --jsonand job-scoped MCP metadata now use a bounded artifact inventory that covers Markdown, TXT, DOCX, PDF, manifests, QA, verification, calibration, trace, run-state, and recovery artifacts.
Fixed¶
- Deep Research background IDs are persisted at creation and acknowledged only after the owning output boundary verifies all required files are nonempty. Normal completion, recovery, strategy, vendor, MCP, runner, and Accordion paths now retain recoverability when output finalization is partial.
- Preflight no longer launches a billable background Deep Research job solely to test connectivity.
[1.34.49] - 2026-07-10¶
Fixed¶
primr --check-jobsis now a read-only cloud and local status view. Completed jobs remain recoverable until--resume-latestdurably finalizes their outputs, and provider-terminal or connectivity failures return a nonzero status instead of a false success.- Recovery output now derives a missing company name from the working path, omits absent fields instead of printing
unknown, and documents platform-neutral inspection, explicit finalization, and retry behavior consistently.
[1.34.48] - 2026-07-10¶
Added¶
- Calibration baseline gate recommendations now report whether the per-report
Confirmed traceability floor is complete. A ready baseline with some reports
lacking decidable
(Confirmed)claims remains report-only with the explicitincomplete_confirmed_traceability_floorreason, report counts, and an operator-review item documenting why the hard gate should stay unset. - Calibration baseline
next_actionsnow carries the same body-free hard-gate action state as baseline inspection JSON. Ready-but-report-only baselines name whether the Confirmed floor is absent, incomplete, or zero, including the selected-report counts that explain whyPRIMR_EVAL_MIN_CONFIRMED_TRACEABILITYstays unset. - Calibration baseline artifacts and inspection JSON now include a body-free
operator_decision_templatethat lists the allowed gate decisions, required review items, and selected-report counts an operator must review before documenting either a deliberate report-only decision or a manual hard gate assignment. The template does not record a decision and still forbids automatic gate arming. primr calibrate --baseline-decision-from ... --baseline-decision-out ...now writes a body-freeprimr.calibration_gate_decision_record.v1artifact after validating the requested decision against the inspected baseline's allowed decisions. The command records reviewer, rationale, selected-report evidence, and baseline fingerprint metadata, but never applies or exports the hard-gate environment variable.primr calibrate --inspect-baseline-decision ...now prints a body-freeprimr.calibration_gate_decision_inspection.v1readback that checks a saved decision record against the current baseline fingerprint and allowed-decision evidence before downstream loops trust it.
Fixed¶
- Release automation now accepts only an exact tag contained in
mainafter a successful CI run for that commit. Same-tag runs are serialized, versioned changelog notes are mandatory, release tooling is lockfile-backed, and PyPI filenames and SHA-256 hashes must match the built wheel and source archive before the GitHub release is created. - CI now builds the documentation site in strict mode, and the locally testable release verifier rejects missing, extra, or mismatched distribution files.
- The locked development toolchain now uses pip 26.1.2, and CI no longer carries the obsolete pip advisory exception.
- Python support is now consistent at 3.12+ across setup,
primr init,primr doctor, both container images, AWS Lambda, Azure Functions, Ruff, dependency guidance, CI, and release builds. New cross-surface integrity tests derive their assertions from package metadata so unsupported runtimes cannot silently return. - Human dry-runs now keep the recovery preview concise by default and end with
explicit launch, monitoring, interruption-recovery, and artifact-retrieval
steps.
--verboseretains the serialized recovery policy, while--jsonremains one machine-readable object. - Long-running phase banners now display caller-supplied duration expectations, making existing 5-30 minute waits visible without changing quiet-mode output.
primr init --helpandprimr doctor --helpnow show concise command-specific options and examples instead of the full global research and evaluation flag inventory. Root help remains unchanged as the complete reference.- Explicit local-only calibration dry runs and pack manifests now report zero
estimated cloud spend. Auto mode quotes its cloud fallback ceiling, while
cloud and cloud-vs-local comparison plans retain their bounded paid-call
estimate. Nonzero sub-cent estimates no longer render as
$0.00. - Release integrity now pins the editable Primr version in
uv.lockto the canonical package version. Every CI install and the release SBOM export use uv's locked mode, so stale project metadata cannot be silently installed or published. - The source-distribution manifest no longer requests removed dependency and pytest configuration files or absent documentation example formats, reducing avoidable packaging warnings while preserving the existing agent, test, log, output, and build-artifact exclusions. CI now builds and inspects the actual source archive to enforce that inventory rather than trusting manifest text.
[1.34.47] - 2026-07-08¶
Fixed¶
- Final Markdown shipping now normalizes long dash punctuation at the artifact boundary, including the old Deep Research runner path. Long dash characters in prose are converted before write, while source URLs percent-encode long dash code points instead of mutating URL semantics.
- DOCX conversion now removes the fast report header metadata line before rendering subtitles, so the Strategic Overview date and website appear once instead of once in the generated subtitle and again in the body.
Added¶
- Calibration baseline artifacts and inspections now include a
measurementstatus block. Ready operator-curated multi-report baselines reportmeasured_operator_curated_multi_report_baselinewith representative coverage, evidence review, and judge agreement checks made explicit in JSON and Markdown. - Roadmap and next-step docs now track the MCP
2026-07-28release candidate as a post-final compatibility review item for Primr's HTTP MCP transport, task lifecycle, schema handling, trace propagation, Apps extension posture, and authorization model.
[1.34.46] - 2026-07-04¶
Changed¶
- Internal refactor (no behavior change): the deep-research run's finalization
stage - cost reconciliation, the estimated-vs-actual summary, the report
trust row, usage recording, and the job summary - moved out of
research_agent.pyinto a dedicated, unit-testeddeep_run_summarymodule, mirroring the existing fast-run seam. Output, cost, and usage behavior are identical; this keeps the orchestrator under its size ceiling and gives the deep path a tested home for future trust and cost surfaces.
[1.34.45] - 2026-07-03¶
Fixed¶
- Cost estimates now price
--verify(post-QA claim verification) on all three surfaces that price a run for approval - the interactiveProceed?confirm prompt,--dry-run, and the--budgetpre-flight gate. Previously none of the three priced it, so a--verifyrun was approved against a number that omitted its verification overhead. The two CLI-config surfaces (--dry-runand the--budgetgate) now share a single estimate-shaping helper so they cannot drift apart again. - The interactive confirm prompt now also prices
--grok-tier, which it ignored while--dry-runand the--budgetgate already accounted for it; a--grok-tier maxrun no longer confirms against a hybrid-tier price.
Added¶
- A deterministic, judge-free label-citation coverage signal: how many
(Confirmed)/(Reported)claims carry a resolvable citation (theno_sourceslice). It is the always-on, zero-cost complement to the opt-in paid label-honesty pass (which judges whether a source supports a claim) - a(Confirmed)claim citing nothing is a structural honesty defect regardless of phrasing. It is computed once in the fast-run QA metrics (traceable_labeled_claims,traceable_labeled_claims_cited,label_citation_coverage_rate) so it is machine-readable for eval, and the report trust summary renders it as a "Label Citations" row. Report-only (a signal, never a gate), reusing existing label/citation extraction with no LLM calls and no network requests. - The deep and
--premiumDeep-Research paths now show the same report trust summary the fast path does - an always-on "Label Citations" row counting how many(Confirmed)/(Reported)claims cite a resolvable source. Previously only fast-mode runs surfaced any trust signal; a deep or premium run finished with no label-traceability visibility at all. Both paths render the identical row through a single shared formatter (label_citations_trust_row), so they cannot describe the signal differently. Report-only, no LLM calls, no network.
[1.34.44] - 2026-07-03¶
Security¶
- The hiring-signal block inside
insights.txtis now fenced as data. It carries verbatim scraped posting titles/locations (raw on the triage and extraction fallback paths), andinsights.txtis read unfenced by the AI-strategy prompt and becomes the analysis workbook on the workbook-fallback section-writing path - so it was the one hiring→prompt boundary still reaching the model unfenced and unsanitized.docs/SECURITY.mdT1 updated accordingly.
Fixed¶
- The interactive cost-confirmation gate (
display_cost_estimate) now prices--strategy-typedocuments, like--dry-runand the--budgetpre-flight gate already do. It previously understated fast-mode runs (a whole strategy bundle) and overstated non-fast placeholder/multi-vendor runs, so the number the user approved diverged from both the dry-run and the actual spend. (The confirm gate still omits--premium/--verify/--grok-tiershaping that the--budgetgate passes; full parity is tracked on the roadmap.) - Cost estimates that list
aialongside another--strategy-typeno longer silently drop the AI-strategy cost: when the explicit list namesai, the runtime runs it too, so it stays priced instead of being replaced.
Documentation¶
- Fixed two
docs/API.mdhook examples that importedCostGuardHookfromprimr.agentic.hooksafter it moved toprimr.agentic.cost_guard(re-exported from theprimr.agenticpackage). - Refreshed docs for the 1.34.43 "hiring signals on the Deep Research paths"
change: RUN_MODES deep/premium rows, the deep-mode architecture diagram,
and the CLI epilog now reflect the hiring pre-stage and its time bump, and
the
show-usagecost-variability section is documented in RUN_MODES.
[1.34.43] - 2026-07-03¶
Security¶
- Fast-mode prompts now fence scraped text as data at these previously
unfenced boundaries: the analysis-workbook and section-writer
corpus/external-source blocks, hypothesis-tree inputs, gap-analysis
summaries, report and strategy regeneration evidence, hiring-signal triage
and extraction prompts (raw titles and job-description bodies were
interpolated unfenced), and the verbatim scraped-external block inside
insights.txt- which also covers the workbook-fallback and strategy context paths that embed it. Strategy context additionally fences the scraped-adjacent working artifacts (hiring signals, recon context). Fencing happens once per run after slicing, so the byte-identical cached prompt prefix is preserved.docs/SECURITY.mdT1 now enumerates fenced vs sanitize-only boundaries instead of claiming blanket coverage, and documents the laundered-injection residual explicitly.
Fixed¶
- Long-lived server processes (MCP, A2A) no longer bleed a prior job's Gemini spend into later jobs: every job now starts with a full usage accounting reset (Grok session + Gemini client) via a single seam, so budget checkpoints stop tripping early on inherited spend and persisted per-run costs stop inflating.
-
--dry-runand the--budgetpre-flight gate now price--strategy-typedocuments, mirroring the runtime exactly: fast mode adds one writing bundle per document on top of the AI strategy, non-fast modes replace the AI strategy with the explicit type and add a flat Deep Research task for the types that consume one, and placeholder types the run would skip are called out in the estimate notes instead of being priced. A YAML strategy previously appeared nowhere in the estimate, so a run could be approved under a ceiling it would predictably exceed. The post-run estimate-vs-actual summary uses the same pricing. -
Multi-vendor AI-strategy runs now re-check an active
--budgetceiling at each vendor dispatch instead of only at stage entry, so spend that accrues while other vendors run can no longer push the run past the ceiling by a full strategy per remaining vendor. - Session token counters are now mutated under a lock; the parallel section writers and strategy vendor threads could previously lose a call's tokens to a read-modify-write race, silently understating the spend that budget checkpoints read.
show-usagehistory no longer duplicates records when one process saves after multiple runs (MCP server, batch evals): each session record is flushed intousage_history.jsonexactly once, and a failed save can be retried without duplication.- Fast-mode usage records no longer price free DDG searches at the paid
grounding rate (a typical run persisted about $1 of phantom search cost,
more than doubling the recorded spend of a sub-$0.80 run). Search cost is
now priced by the active provider; query counts are still recorded, and
show-usagesums the recorded per-run search cost instead of projecting all historical queries at the paid rate. RunBudget.sync_spendis now a single atomic write. The per-vendor budget checkpoints run from parallel strategy threads, and the previous reset-then-record pair could interleave to double the recorded spend and falsely skip strategies that had headroom.
Added¶
- Hiring signals now ride into the CLI Deep Research paths (
--premiumand--mode deep), not just fast mode: the same ATS/careers-page stage runs before the deep phase and its block joins the stage-1 context the comprehensive report call consumes - fenced as data, recorded in run state and_hiring/artifacts, still reaching the deep call when a run continues past a failed structured phase, and skipped for strategy-only and legacy hybrid runs (hybrid never consumes stage-1 context). Deep and complete dry-run estimates note the hiring stage and carry its 1-2 minute duration bump; MCP/A2A jobs run the orchestrator directly and are not yet wired (tracked on the roadmap). output/andworking/now document themselves: primr writes a top-levelREADME.mdinto each when it creates them (once; user edits are never overwritten) explaining what lives there and what is safe to delete -working/holds resumable per-run intermediates including_run_state.json, whileoutput/holds finished deliverables plus the MCP/A2Arun_manifest.jsonaudit records, with no resume state.primr show-usagenow includes a "Cost Variability" section per observed mode: prior-history average cost with lifetime standard deviation, recent-5 average with percent delta, and prior-vs-recent cache hit rates, with a report-only SIGNAL line when recent runs cost >25% more or cache >10 points less than prior history - the continuous-reasoning / prompt-cache regression surface the sub-$1 default depends on. Fast runs also persistcache_hit_rateinto_run_state.jsonfor post-hoc analysis.
Changed¶
-
Strategy generation prompts are now split into a run-shared cached prefix (company report + working-folder artifacts, built once per stage loop) and a per-strategy volatile suffix (vendor research docs + strategy prompt), extending roadmap #8's prompt-cache preparation from section writing to the strategy stage. The assembled prompts are byte-identical to before, so providers' implicit prefix caching keys on the shared context across multi-vendor and multi-strategy runs; artifacts are also read once per run instead of once per strategy.
-
Windows working-directory hardening (roadmap #14): all temp-write + rename state-persistence paths now go through the single
atomic_replaceseam that retries transient sync-client/antivirus file locks - run-state checkpoints, pending Deep Research jobs, the update-check cache, and host-marker state previously carried their own rename logic.primr doctornow probes that same atomic write path againstoutput/andworking/, so OneDrive-style lock contention surfaces in doctor before it bites a live run.docs/CONFIG.mddocuments keeping high-churnworking/andlogs/paths outside synced folders.
[1.34.42] - 2026-07-01¶
Changed¶
- Internal/eval
agentprofile unavailability now fails closed for the remaining routed utility stages that do not yet have host adapters. This is not a public CLI profile.fast.scrape_summarywrites deterministic source excerpts,fast.hiring_signalsuses deterministic triage plus posting metadata, both stages record body-freeagent_profile_unavailableroute fallbacks, and neither stage silently calls a cloud LLM when no official host runner qualifies. - Hiring-signal deterministic selection helpers now live in a focused
hiring_signal_selectionmodule so the orchestration file stays below its architecture ratchet while preserving existing triage behavior.
[1.34.41] - 2026-07-01¶
Security¶
- Hardened security-scan posture for current code scanning: CodeQL now uses a
production-scope config for
src/,deploy/, andscripts/instead of raising alerts from test fixtures; URL allow/deny checks now parse hostnames; JavaScript-only page detection uses the HTML parser rather than a tag regex; console output now redacts secret-shaped values; rate-limit logging no longer emits caller bucket identifiers; role-plan and stage-eval artifacts mask accidental secrets before persistence through a shared redacted-write helper; helper scripts no longer print or write generated search API keys directly to.env; the user key store now uses the same low-level restrictive write path across platforms; Cosmos status queries are parameterized; and API-key fingerprints use deterministic PBKDF2-HMAC-SHA256 digests where compatibility allows. GitHub Actions workflows now default to read-only token permissions, CI checkouts no longer persist credentials, and Dependabot is configured for uv and GitHub Actions dependency updates. Azure Functions deployment requirements now enforce the same secure Azure SDK floors as the main project. - Cleaned up credential-shaped test fixtures and public Azure role-definition
literals so local secret scanning now passes on current
src/,docs/,tests/, anddeploy/paths without masking real leaks. GitHub secret scanning remains at zero open alerts.
Added¶
- Added a body-free operator-review block to calibration baseline artifacts and baseline inspection output. Ready baselines now state that automatic gate arming is disallowed, list the measured review items an operator must check, surface cloud-vs-local disagreement counts, and distinguish gate candidates from report-only recommendations without exposing report bodies or raw claims.
- Added dedicated public-board hiring-signal adapters for iCIMS and BambooHR. Because their official job APIs require authenticated customer or partner access, Primr now probes their public hosted career portals through bounded SSRF-safe HTML fetches and feeds the resulting postings through the existing triage/body-fetch/extraction path.
- Added a canonical protected-site page-access eval corpus at
tests/fixtures/page_access/protected_site_trace_corpus.json. The corpus is built from sanitized traceaccess_assessmentrecords only, covers major challenge and recovery tags, and includes known false-positive and false-negative historical cases without committing raw HTML, URLs, page bodies, company names, or provider payloads. - Added
primr --eval --eval-page-access-fixture <fixture.json>for operator-facing page-access classifier evals. The command reads labeled sanitized HTML cases or trace-derivedaccess_assessmentpredictions, then writes false-positive/false-negative JSON, Markdown, and scorecard-input quality evidence underoutput/evals/<eval-id>/page_access_stage/without copying raw HTML, URLs, or page bodies. - Added a body-free offline page-access classifier eval helper. Labeled local fixtures or trace-derived predictions now produce true/false positive and false-negative metrics, tag-level breakdowns, and JSON/Markdown review artifacts without copying raw HTML, URLs, or page bodies.
- Added first-party PDF recovery to the blocked-origin fallback fan-out. The
new source discovers same-site PDFs from priority investor/news/about/help
landing pages, adds bounded direct PDF probes, ranks likely annual reports,
fact sheets, overviews, media kits, and guides first, and extracts text
locally with PyMuPDF only as
source="first_party_pdf". - Added first-party JSON-LD structured-data recovery to the blocked-origin
fallback fan-out. The new source probes bounded priority same-site pages,
extracts Organization / NewsArticle / Product / Event / Person facts with
stdlib parsing, filters same-site URLs, caps HTML/entity/output budgets, and
returns
source="structured_data"through the existing SSRF-safe HTTP seam without invoking any paid AI provider. - Added durable host-level positive-marker learning for verified page access.
Once a confirmed real first-party page matches explicit company or host
markers, Primr persists a bounded, filtered marker set under
PRIMR_DATA_DIRand reuses it to classify later pages on the same host without provider calls. - Added clearer blocked-site CLI summaries when live first-party scraping and same-site recovery both fail. The summary now shows sanitized evidence, same-site recovery count, and the next fallback action before public-data recovery starts.
- Added A2A
read_report_by_job, an explicit report-scoped owned-job report read backed by the same MCPprimr://output/report/by_job/{job_id}helper, withcontent_mode,artifact_type, andmax_charsoutput negotiation.
Changed¶
- Added browser render-snapshot comparison to page-access classification. Playwright, DrissionPage, and Patchright browser tiers now compare initial and final rendered DOM text as compact evidence, so cleared challenges and stable real pages are less likely to be mistaken for thin interstitials while persistent challenge templates still escalate.
- Updated the Anthropic balanced model to Claude Sonnet 5 (
claude-sonnet-5) with conservative post-intro price estimates, 128k max output, Sonnet 4.6 back-compat registration, request guards for models that reject sampling parameters, Sonnet 5output_config.effortsupport, and validation for the current adaptive-thinkingdisplayvalues. - Expanded Anthropic Messages request shaping for current adaptive-thinking
models:
output_config.effortnow acceptsmaxandxhigh, Sonnet 5 can explicitly disable adaptive thinking, adaptive display config is preserved, and legacy manual thinking budgets are omitted on tiers that reject them. - Rejected assistant-prefill-shaped Anthropic requests locally for current Claude model families that return provider-side 400s, including Sonnet 5, Sonnet 4.6, Opus 4.6 and later, Fable 5, Mythos 5, and Mythos Preview.
- Applied a 30% tokenizer safety factor to dry-run estimates for any routed cost bucket that uses Claude Sonnet 5, matching Anthropic's migration guidance that the same text can tokenize larger than Sonnet 4.6.
- Raised the optional Anthropic SDK floor to
anthropic>=0.109.1so installed Claude support matches the current Messages API request shape. - Redacted xAI browse/search logs to scheme and host only, and stopped logging provider error-body snippets on failed browse calls so customer URL paths, query strings, userinfo, and provider diagnostics do not enter logs.
- Made Cowork skill-pack icon generation local by default. Remote image
providers, including xAI Grok Imagine, now require the explicit CLI
--remote-iconsflag or MCPremote_iconsargument so configured provider keys cannot silently create image API spend. Skill-pack estimates now include a conservative remote-icon allowance when that opt-in is set, and MCP approval tokens bind theremote_iconschoice. - Closed two additional hidden-spend paths: missing or stale vendor-research
cache no longer triggers Deep Research unless explicitly enabled, and Gemini
PDF extraction is disabled by default in favor of local PyMuPDF parsing unless
PRIMR_PDF_LLM_MAX_CALLSis set. - Kept authenticated MCP
check_jobs,primr://output/latest, andprimr://output/by_job/{job_id}metadata-first even forreport-scoped callers, and made A2Acheck_jobsreturn explicit compact resource URIs instead of raw output paths. - Added body-free OpenTelemetry span projections and stable
request_idfields to MCP tool, MCP resource, and A2A skill audit events. - Added runtime budget visibility to run manifests and compact usage-summary readback, including the approved ceiling, active checkpoint status, and non-interruptible required provider tasks without exposing manifest bodies.
- Moved default research memory storage to the per-user data directory
(
PRIMR_DATA_DIRoverride) and reject secret-like memory payloads before durable writes. - Added local
primr company track,company list, andcompany showcommands backed by per-user JSON company profiles with URL/userinfo and secret-like payload rejection. - Added
primr company exportto write local JSON and Markdown profile bundles with persisted hypothesis confidence tags and explicit run-history/claim-store gap markers. - Added bounded body-free run pointers to tracked company profiles so exports include run history when local run metadata has been recorded.
[1.34.40] - 2026-06-30¶
Changed¶
- Calibration baseline next-action commands now write operator scratch files
under the gitignored root
.agent/directory instead ofdocs/.agent/. - Calibration pack manifests now include report and sidecar byte sizes plus SHA-256 content hashes, and baseline readiness JSON carries those fingerprints forward.
- Calibration baseline inspection now reports missing or mutated fingerprinted report and sidecar artifacts without returning report bodies.
- Ready calibration baseline artifacts now publish a report-only
PRIMR_EVAL_MIN_CONFIRMED_TRACEABILITYgate recommendation from the per-report Confirmed traceability floor. - Stage runtime routing can now consume sanitized provider availability snapshots and carry body-free availability metadata into route logs while preserving the existing legacy fallback path.
- Stage routing now collects sanitized env-only cloud provider availability snapshots by default, skips local probes in normal runs, and maps Gemini availability rows onto Google-owned model configs.
- Routed fast utility stages now append measured token/cache/cost deltas to
body-free
stage_routesrecords when provider counters expose them. - Stage route comparison helpers now aggregate body-free run-state route records into JSON/Markdown summaries by stage, backend, and profile.
- Stage eval scorecards now join route comparison rows with explicit quality evidence to classify candidates for human review without auto-promotion.
primr --eval --eval-stage-scorecardnow writes routed-stage scorecard JSON/Markdown artifacts from_run_state.jsonroute ledgers plus explicit quality evidence JSON.- MCP now exposes
primr://eval/stage_scorecard/{eval_id}as a compact readback resource for CLI-generated stage scorecards, omitting prompts, responses, quality-source bodies, report bodies, and raw run-state content. - A2A now advertises
read_artifacts_by_jobas a read-scoped compact artifact metadata skill backed by the same ownership-gated by-job contract as MCP. - A2A now advertises
read_qa_summary_by_jobas a read-scoped compact QA summary skill backed by the same ownership-gated by-job contract as MCP. - A2A now advertises
read_usage_summary_by_jobas a read-scoped compact usage and cost summary skill backed by the same ownership-gated by-job contract as MCP. - A2A now advertises
read_source_summary_by_jobas a read-scoped compact source appendix summary skill backed by the same ownership-gated by-job contract as MCP. - A2A now advertises
read_trace_summary_by_jobas a read-scoped compact scrape trace summary skill backed by the same ownership-gated by-job contract as MCP. - A2A now advertises
read_verification_summary_by_jobas a read-scoped compact claim verification summary skill backed by the same ownership-gated by-job contract as MCP. - A2A now advertises
read_calibration_summary_by_jobas a read-scoped compact label-calibration summary skill backed by the same ownership-gated by-job contract as MCP. - A2A
estimate_researchnow returns MCP-equivalent approval-token fields, and A2Aresearch_companyenforcesmax_estimated_cost_usdplus a matching token when cost-cap enforcement is active before job creation, propagating the accepted cap intoPipelineRunneras the runtime budget. - A2A now advertises
read_stage_scorecardas a read-scoped compact scorecard summary skill backed by the same eval-id resource boundary as MCP. - Website-summary local stage evals now write
website_summary_stage_quality_evidence.json, giving routed-stage scorecards structured quality evidence without copying local summaries, baseline summaries, prompts, or run-state bodies. - Website-summary local stage evals can now add
--eval-local-stage-semantic-judgeto run a local OpenAI-compatible semantic judge pass, write body-free semantic eval artifacts, and feed the resulting review-only quality evidence into same-command stage scorecards. - The semantic judge model option now accepts a comma-separated local judge panel and records agreement-rate plus score-spread metadata without changing review-only promotion policy.
- An internal/eval-only Codex CLI host-runner pilot now covers
fast.source_relevance: Primr invokes officialcodex execwith a read-only sandbox, no approvals, disabled web search/shell tool config, a JSON-array schema, and body-free route metadata. If no official host runner is available, the internal agent profile keeps all sources instead of silently falling back to cloud API spend. The public CLI remainscloud|hybridbecause Codex authentication does not prove whether execution is plan-backed or API-key billed. - The
fast.source_relevancehost-agent packet now passes source snippets as fenced evidence blocks rather than embedding untrusted snippets in host-agent instructions. primr --eval --eval-source-relevance-fixturenow writes body-free precision, recall, F1, exact-match, and stage quality evidence for review-onlyfast.source_relevancescorecards.- Agentic QA fallback scoring no longer assigns a default passing accuracy
score when it has not verified factual accuracy; the compatibility
accuracydimension now reflects deterministic traceability signals only. - Source distributions now explicitly prune
.agent/while retaining the legacydocs/.agent/prune rule. - Local
_site/documentation build output is now gitignored.
[1.34.29] - 2026-06-29¶
Added¶
- Routed
fast.hiring_signalsthrough the stage capability router behind--inference cloud|hybrid, preserving fail-open behavior and the legacy utility fallback path. - Added capped body-free
stage_routesrecords for hiring-signal runs with backend/profile/billing metadata, route/fallback reasons, expected token budget, discovered role count, extracted role count, duration, outcome, and failure class.
Changed¶
- Hiring-signal LLM triage and extraction now receive the routed model from
ai/stage_routing.pywithout changing ATS discovery, careers-page egress, prompt bodies, output artifacts, or fail-open behavior. - Extracted hiring-signal artifact rendering and persistence into
data/hiring_signal_artifacts.py, keepingdata/hiring_signals.pybelow its architecture line ceiling while preserving the existing public helpers.
[1.34.28] - 2026-06-29¶
Added¶
- Routed
fast.scrape_summarythrough the stage capability router behind--inference cloud|hybrid, preserving today's legacy scraping model as fallback. - Added capped body-free
stage_routesrecords for scrape summary runs with backend/profile/billing metadata, route/fallback reasons, expected token budget, input page count, output summary count, duration, outcome, and failure class.
Changed¶
- The website summarizer now passes the selected routed model into the existing
llm()seam without changing prompt bodies, output files, scraping egress, or fallback behavior.
[1.34.27] - 2026-06-29¶
Added¶
- Added capped body-free
stage_routesrecords to_run_state.jsonfor routed stages, starting withfast.source_relevance. - Route records include stage id, inference profile, backend id/kind, declared billing category, route/fallback reasons, expected stage token budget, latency, source counts, and failure class when fallback occurs. That category records routing policy and does not prove an external host session's billing basis.
Changed¶
- Extracted source-relevance filtering into
core/source_relevance.pyand lowered theresearch_agent.pyarchitecture line ceiling.
[1.34.26] - 2026-06-29¶
Added¶
- Added
--inference cloud|hybridas the first production capability-routing profile switch. - Added
ai/stage_routing.py, a runtime bridge that resolves declared production stages through the pure capability router while preserving the legacy model as fallback.
Changed¶
fast.source_relevancenow consumesroute_stage()before its LLM call, logs safe route metadata, and passes the routed model into the existingllm()provider seam.llm()now accepts an explicit model override so stage-level routing can select a model without adding another provider dispatch path.
[1.34.25] - 2026-06-29¶
Changed¶
- Cost estimates now expose live input, cached input, cached-input cost, and long-context surcharge fields through a shared token-cost breakdown.
- OpenAI GPT-5.x registry entries now carry long-context tier metadata across the mini and nano variants as well as the flagship entries.
- Historical cached-token averages now feed cost estimates when present, while pre-run estimates do not assume prompt-cache savings before a run observes actual cache hits.
[1.34.24] - 2026-06-29¶
Changed¶
- Gemini terminal quota guidance now lives in
GeminiProvideras a provider-owned guidance object. The legacyllm()path renders that guidance generically, preserving the current colored CLI output and[ERROR] Daily API quota exhausted. Cannot continue.failure message. - Backend-freedom docs now mark the xAI browse/search seam and Gemini quota UI seam as provider-owned, leaving long-context/cache-token estimate honesty as the next backend-freedom slice.
[1.34.23] - 2026-06-29¶
Added¶
- Added
XAIProvider, a provider-owned xAI class that inherits the existing OpenAI-compatible Grok chat behavior and owns the xAI Responses API browse/search surrogate.
Changed¶
grok_browse_and_summarize()is now a thin compatibility wrapper aroundXAIProvider.browse_and_summarize(). It preserves the public dictionary shape and mirrors token usage into existing Grok session counters for cost reporting.- Provider registry construction now returns
XAIProviderfor the xAI row, so xAI chat and xAI-only browse/search behavior share one provider-owned seam.
[1.34.22] - 2026-06-29¶
Added¶
- Added
core/stage_inventory.py, a typed production-stage capability inventory for backend-freedom wiring. It declares fast-mode and premium deep-research stage ids, modules, roles, reasoning/trust requirements, context and token estimates, egress/deep-research/structured-output needs, accepted backend families, budget checkpoints, current backend ownership, promotion gates, and emitted artifacts without changing runtime routing. - Backend-freedom docs now cite current OpenTelemetry, OpenAI, Anthropic, and Gemini guidance for GenAI telemetry and prompt/context caching, and identify the first three low-risk utility stages for future local or host routing.
[1.34.21] - 2026-06-29¶
Changed¶
- Calibration baseline readiness now requires explicit
primr.calibration_pack_selection.v1metadata with non-empty representative tag requirements before a pack can be marked ready. Latest-N manifests now reportmissing_representative_selectionand stay report-only until an operator-curated representative selection is attached. - Baseline Markdown and JSON inspections now expose representative selection readiness directly so agents and operators do not mistake missing selection metadata for complete representative coverage.
[1.34.20] - 2026-06-29¶
Added¶
- A2A skill invocations and task cancellation now append privacy-preserving audit events to the shared agent audit JSONL with transport, skill name, outcome, hashed arguments, hashed results, hashed caller ids, granted scopes, duration, and job id when present.
- A2A audit events cover successful skill calls, insufficient-scope denials, handled validation errors, and cancellation requests without storing raw message text, company URLs, report paths, task ids, raw results, or caller ids.
[1.34.19] - 2026-06-29¶
Changed¶
- Refreshed operator-facing docs for the current default run shape: xAI plus
Gemini cost guidance, default AI Strategy generation,
--no-ai-strategybase-report guidance, current security supported-version line, and 10,000+ test-suite wording.
[1.34.18] - 2026-06-29¶
Added¶
- A2A authenticated requests now bind their bearer-token identity into the shared MCP auth context before skill dispatch.
- A2A skill dispatch now enforces the same
readandresearchscope split as MCP forestimate_research,check_jobs,system_health,research_company,run_qa, and task cancellation, while preserving local unauthenticated loopback behavior and legacywritecompatibility. - Authenticated A2A jobs are now owned by the bearer token
client_id, socheck_jobs, QA auto-targeting, and cancellation do not cross client boundaries.
[1.34.17] - 2026-06-29¶
Added¶
- Label calibration now checks cited
(Estimated)and(Hypothesis)claims for deterministic source-copy leakage while keeping inference-class labels exempt from traceability. - Calibration sidecars, offline eval scorecards, CSV exports, and calibration
baseline artifacts now surface
source_copiedandinference_source_copiedas report-only signals until a representative baseline defines acceptable behavior.
[1.34.16] - 2026-06-29¶
Added¶
- MCP
resources/readcalls now write privacy-preserving audit events withevent_type, normalized resource kind, hashed resource URI, hashed result body, job id when present, granted scopes, duration, and outcome. primr://agent/audit/recentnow reports both tool-call and resource-read events to local stdio callers and admin-scoped HTTP callers without storing raw URI query values, resource bodies, raw arguments, raw results, raw caller ids, or approval tokens.
[1.34.15] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/calibration_summary/by_job/{job_id}as an ownership-gated, compact label-calibration summary resource for one job. It summarizes attached.calibration.jsonartifacts and standard calibration sidecars adjacent to owned report artifacts. - Calibration summaries return per-label traceability counts, evidence-review count buckets, judge provenance, and judge-agreement metadata without returning raw claims, source URLs, evidence reviews, rationales, or report body content.
[1.34.14] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/verification_summary/by_job/{job_id}as an ownership-gated, compact claim verification summary resource for one job. It returns trust score, claim counts, status counts, first-party downgrade counts, and source-reference counts without returning raw claims, source URLs, search queries, explanations, or report body content. - MCP verification runs now attach same-run
verification.jsonartifacts to job metadata, including fast-mode MCP runs, so destination copies and job-scoped resource reads carry the verification artifact.
Fixed¶
- CLI fast-mode research now honors
--verifyinstead of returning before the post-run claim verification step.
[1.34.13] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/trace_summary/by_job/{job_id}as an ownership-gated, compact scrape trace summary resource for one job. It returns tier attempts, success rates, latency summaries, block counts, HTTP status counts, and validation health without returning URLs, final URLs, raw trace entries, or page content. - Same-run scrape trace JSONL files are now attached to MCP job metadata when present, bounded by the job's company slug and run window.
[1.34.12] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/source_summary/by_job/{job_id}as an ownership-gated, compact source appendix summary resource for one job. It returns citation counts, source definition counts, missing and unused citation numbers, duplicate URL counts, source domains, and source URLs without returning report body content.
[1.34.11] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/usage_summary/by_job/{job_id}as an ownership-gated, compact run manifest summary resource for one job. It returns cost, timing, approval, execution, parse, hash, timestamp, and artifact-count metadata without returning company URLs, approval tokens, manifest artifact lists, or full manifest content.
[1.34.10] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/qa_summary/by_job/{job_id}as an ownership-gated, compact QA summary resource for one job. It returns score, status, count, parse, hash, timestamp, and top-level-key metadata without returning detailed report or QA body content.
[1.34.9] - 2026-06-28¶
Changed¶
- Documentation now describes the job-scoped artifact metadata MCP resource across API, agent integration, artifact pipeline, security, OpenClaw, README, hosted-agent guides, bundled skills, and design surfaces.
[1.34.8] - 2026-06-28¶
Added¶
- MCP now lists and serves
primr://output/artifacts/by_job/{job_id}as an ownership-gated, compact artifact metadata resource for one job. It returns file names, paths, sizes, hashes, timestamps, and missing-file state without report body content.
[1.34.7] - 2026-06-28¶
Changed¶
primr calibrate --inspect-selection <selection.json>now prints a zero-spend, machine-readable inspection of curated calibration selection files, including report count, required tags, present tags, missing tags, per-report tags, and operator next actions before any pack manifest or judge work runs.
[1.34.6] - 2026-06-28¶
Changed¶
primr calibrate --pack-selection-template <selection.json>now writes a zero-spend curated selection starter from resolved reports, including the default representative tag checklist while leaving each report's tags empty for operator curation.primr calibrate --pack-selection <selection.json>now accepts curated calibration-pack selection files that list exact report paths and operator-supplied representative coverage tags. Pack manifests persist the declared required, present, and missing tags, and baseline readiness artifacts reportmissing_representative_coveragewhen a declared required tag is not represented.- Calibration baseline readiness now requires every selected report to have evidence-review dimensions and a cloud-vs-local judge-agreement record. A pack with only partial sidecar coverage remains not ready, and the JSON plus Markdown summaries show the missing report counts.
- Calibration baseline report summaries now include per-report evidence-review counts and judge-agreement compared-claim counts, so operators can identify the exact selected artifacts still blocking baseline readiness.
primr calibrate --inspect-baseline <baseline.json>now prints a zero-spend, machine-readable readiness inspection with report-level blockers, missing representative tags, gate policy, and suggested rebuild commands.- MCP clients can read
primr://calibration/baseline/inspection?path=<baseline.json>for the same readiness inspection, with the path constrained by the existing MCP allowed roots.
[1.34.5] - 2026-06-28¶
Changed¶
- Calibration baseline readiness artifacts now include structured
next_actionswith missing report and sidecar counts, reason-specific remediation, suggested calibration commands, and an explicit gate policy that keepsPRIMR_EVAL_MIN_CONFIRMED_TRACEABILITYunset until the pack is ready and the measured floor has been reviewed.
[1.34.4] - 2026-06-28¶
Fixed¶
- Generated skill-pack verifier scripts now perform real deterministic artifact
checks instead of shipping placeholder verification code. The fallback
scripts/verify-artifact.pychecks that the artifact exists, is readable, and has enough non-whitespace content to review. - Markdown, HTML, and plain-text report template renderers no longer add visible author or generated-by attribution lines while retaining metadata fields for compatibility.
[1.34.3] - 2026-06-28¶
Changed¶
- Local calibration judging now fails closed when a selected local model call fails, instead of silently falling back to the paid cloud judge. Affected reports are recorded as calibration failures and no sidecar is written for those reports.
primr calibrate --baseline-from <pack.json>now writes a zero-spendprimr.calibration_baseline.v1readiness artifact from a frozen calibration pack manifest, with optional Markdown via--baseline-md. The artifact summarizes traceability, evidence-review coverage, judge agreement, and explicit not-ready reasons without arming a quality gate.
[1.34.2] - 2026-06-27¶
Security¶
- MCP
research_companynow propagates the approvedmax_estimated_cost_usdinto the background pipeline runner as the active run budget. The fast pipeline therefore consults the same mid-run budget checkpoints as the CLI--budgetpath, rather than treating the MCP cap as a pre-flight estimate check only. The runner clears the process-global budget in afinallyso a completed, cancelled, or failed job cannot leak budget state into the next job. Pinned by MCP tool-dispatch and runner regression tests. - Budget estimates now expose their runtime-enforcement semantics explicitly.
CLI help, human dry-runs,
--dry-run --json, and MCPestimate_runnow distinguish fast full-report optional-stage checkpoints, non-fast optional strategy checkpoints, and estimate-gated-only paths. This keeps agent approval prompts and operator expectations aligned with the actual spend checkpoints. - Non-fast Deep Research runs now consult the active run budget before and
between optional strategy documents. The required Deep Research task remains
estimate-gated once it starts, but premium, deep, complete, and hybrid paths
no longer continue into optional strategy spend after observed main-run cost
reaches the approved ceiling. Explicit
--strategy-type aiand generic strategy runs now also record the correct flat Deep Research task cost. - Provider-hosted skill-pack image downloads now use the shared
safe_http_get()seam, so every redirect hop is SSRF-validated before connection instead of relying on final-URL validation after automatic redirects. - Deep Research preflight website reachability checks now use
async_safe_http_head(), preserving unsafe-initial-URL and DNS-failure behavior while validating redirects before any intermediate hop is connected. - Workday hiring-signal probes no longer auto-follow redirects for the JSON POST endpoint. Redirect responses are dropped rather than followed unless a future method-preserving per-hop redirect path is added.
managed_http_client()now disables automatic redirects by default, so new utility callers cannot accidentally connect to unvalidated intermediate redirect targets.- CLI dry-run and
--budgetpre-flight estimates now clamp enabled AI-strategy runs to at least one vendor, preventing internally constructed empty platform tuples from zeroing the strategy estimate. - Wayback CDX and replay fetches now delegate to the shared
data/safe_http.pyseam, so archived-content recovery validates every redirect hop before connecting instead of relying on final-url validation. - Discovery HTTP helpers (
data/scraping/net.py) now follow redirects manually and validate every hop before connecting while preserving theirrequests.Responsereturn contract for sitemap and URL-existence checks. HTTPClient.get()andHTTPClient.head()now follow redirects manually and validate each hop before connecting while preserving pooled session, retry, stats, and nativerequests.Responsebehavior.- Tiered HTTP scrapers (
scrape_with_requests,scrape_with_httpx, andscrape_with_curl_cffi) now follow redirects manually and validate every redirect target before connecting while preserving each tier's transport identity and raw-content result contract. - Google grounding citation resolution now uses
data/safe_http.py:async_safe_http_head(), so async HEAD resolution validates every redirect hop before connecting and returns the original citation URL instead of falling back when the SSRF guard blocks a hop. - The shared safe HTTP seam now resolves each validated hop once and connects to that validated IP literal while preserving the original Host header and HTTPS SNI. This closes the DNS-rebind check/connect split for fallback, hiring, Wayback CDX/replay, and citation HEAD fetches without disabling TLS verification.
- The tiered httpx scraper now uses the same validated-IP connection artifact for every hop while preserving HTTP/2 setup, cookies, original Host, HTTPS SNI, and logical final URLs.
- Requests-family egress now uses a shared
PinnedHTTPAdapterthat resolves each logical request once, connects urllib3 to the validated IP literal, and preserves the original Host header plus HTTPS SNI. The pooledHTTPClientmounts this adapter while keeping retries, pooling, stats, and nativerequests.Responsesemantics; the tiered requests scraper reuses it without changing its raw-content result contract. - The curl_cffi scraper tier now resolves and validates each hop once, passes
the vetted address to libcurl through
CurlOpt.RESOLVE, keeps the logical URL for Host/SNI/TLS impersonation behavior, disables environment proxy trust, and preserves manual redirect validation plus raw-content result semantics. - Chromium-backed browser tiers now derive a browser egress plan from the validated connection artifact. Playwright, Playwright aggressive, vision, and Patchright launch with Chromium host-resolver rules for the validated initial hostname, block service workers where supported, and abort unsafe browser requests through a Playwright-compatible route guard. DrissionPage receives the same initial-host resolver pin through Chromium startup args.
- Chromium-backed browser tiers now also launch through a local loopback egress proxy that validates each browser-discovered HTTP request or HTTPS CONNECT target, dials the validated IP literal, and tunnels TLS without terminating it. Browser launches disable QUIC and loopback proxy bypass so dynamic redirect and subresource hosts stay on the pinned TCP proxy path.
Changed¶
--verifyresults now feed the final Report Trust summary. Contradicted claims surface as a WARN gate with explicit counts instead of appearing only inverification.jsonor the transient verification phase line.primr calibratenow records judge-reported source-level evidence review signals in calibration sidecars, not only traceability verdicts. The sidecar schema now includes support, contradiction, source independence, source authority, reasoning strength, uncertainty honesty, and business relevance counts. The offline eval scorecard surfaces those pooled dimensions in a new## Evidence Reviewsection and CSV columns while keeping them report-only until a defensible baseline and judge-agreement record exist.primr calibrate --judge-comparenow stamps per-report cloud-vs-local judge agreement metadata into calibration sidecars. Offline eval scorecards surface the pooled agreement counts and rate in a new## Judge Agreementsection and CSV columns, keeping judge substitution measurable before any gate is considered.primr calibrate --pack-manifest <path>writes a local JSON manifest of the selected calibration pack, including report paths, sidecar state, estimates, per-label totals, evidence-review summary, and judge-agreement metadata. It also works with--dry-runso baseline candidates can be frozen without provider spend.- Local agent working files moved to gitignored
docs/.agent/, keeping persistent engineering memory out of the project root and tracked docs. - README is now a concise project front door instead of the full manual. Run mode, cost, agent-integration, and skill-pack details now link to focused docs so first-time users can install, estimate, and run without wading through advanced integration material.
- README, the docs index, MkDocs navigation, ROADMAP, and the 1.x/2.0 design notes now point to the same "what next and why" sequence: evidence-grounded validation, backend-freedom wiring, control-plane artifact resources and A2A parity, research memory layer 1, and the continuing maintenance ratchet.
- The next-steps plan now distinguishes evidence-grounded validation from simplistic fact matching. Label traceability is documented as the first measurable slice, while real validation must judge support, contradiction, source independence, source authority, reasoning strength, and uncertainty honesty through layered evals and agreement checks.
- Existing user-facing docs and deployment docs in this pass were normalized away from em dashes and en dashes so the repository style rule is easier to enforce mechanically.
- README now makes command selection, agent-run approval flow, and budget scope
explicit while moving the detailed contributor gate checklist into
docs/CONTRIBUTING.md. - The MkDocs site now builds in strict mode locally and in the GitHub Pages workflow. Remaining root/deploy cross-links use stable GitHub URLs, and the previously orphaned eval and design docs are included in the curated nav.
- Raised the
requestsdependency floor to>=2.34.0because the DNS-rebind pinning adapter depends on the current Requests transport-adapter TLS hook.
Added¶
- Added
docs/NEXT_STEPS.md, a short execution brief explaining what should happen next, why each item comes in that order, what is explicitly not next, and which current best-practice sources informed the plan. - Added
docs/RUN_MODES.mdfor the mode and cost matrix, strategy/platform selection, budget semantics, output locations, and sample run shape. - Added
docs/AGENT_INTEGRATION.mdfor MCP, A2A, host snippets, packaged skills, credential boundaries, and async monitoring guidance.
Fixed¶
PinnedHTTPAdapternow normalizes proxy mappings before callingrequests.utils.select_proxy, preserving runtime behavior while keeping the full mypy gate clean on the Requests adapter boundary.reset_tenant_manager()now closes the previous global SQLite connection before replacing it, and tenancy tests close per-test managers. This removes the resource leak surfaced by running tenancy tests withResourceWarningas an error.reset_knowledge_graph()andreset_company_monitor()now close their previous global SQLite connections before replacing them, and their tests close per-test instances. Full non-manual coverage now passes withResourceWarningand pytest unraisable warnings promoted to errors.run_sync()now usesasyncio.run()from synchronous code and closes rejected coroutine objects when called from an async context. This prevents sync/async bridge tests from leaving event-loop sockets to garbage collection.- The existing pytest
timeoutmarker is now registered, removing the unknown marker warning from the test suite. head_exists()now returnsFalsewhen a redirect target is blocked by SSRF validation instead of propagating aValueErrorthrough discovery.- Final-report and strategy citation cleanup no longer deletes bracketed prose
merely because it contains
cite:inside the bracket. Informal citation cleanup now only rewrites brackets that begin withcite:orcites:, so prose such as[we cite: revenue doubled]is preserved. - Final-report and strategy cleanup no longer strips writer-scaffolding tokens
from Markdown fenced code examples. The same
[workbook],[cite: label],[cross-ref ## ...],[Analysis: ...],[External Sources], vendor-research filename, and word-count markers are still removed from prose, but examples inside fenced blocks now survive.
[1.34.1] - 2026-06-26¶
Security¶
- Closed an intermediate-redirect SSRF in the fail-open fetch fan-out. The
shared HTTP helpers previously followed redirects with
follow_redirects=Trueand validated only the final URL, so an attacker-controlled page could302through an internal address (loopback / RFC1918 / link-local / cloud metadata) that was connected before the post-hoc check ever ran. A new shared seamdata/safe_http.pynow follows redirects manually and revalidates every hop through the central SSRF guard before connecting;fallback_sourcesandhiring_signalsdelegate to it, which also removes the duplicated keep-in-sync helpers. Pinned by a hermetic test that asserts an internal redirect target is validated and never connected to. Later Unreleased hardening extends the same per-hop policy to the remaining fetch seams.
[1.34.0] - 2026-06-25¶
Added¶
- Label-honesty pass (
PRIMR_LABEL_HONESTY=1). A new opt-in pre-ship pass that closes the measured epistemic-grounding gap: a(Confirmed)or(Reported)claim whose cited source is judged not to substantively support it is downgraded to(Estimated). Model judgment decides whether the source supports the claim (reusing the calibration harness's injectable judge); the downgrade is a mechanical, fail-safe rewrite that only ever lowers confidence, never a content regex. Every other verdict (no_source,unfetchable,traceable, inference labels) fails open, so the pass changes a label only on positive evidence of an overclaim. Default-off keeps the standard run byte-identical; when enabled it writes a_label_honesty.jsonaudit sidecar and never blocks shipping. Newqa/label_honesty.pymodule;LabeledClaimnow carries the label's source span so the exact occurrence can be rewritten. - Capability routing can now consume provider availability snapshots through
backend_with_availability()andbackends_with_availability(). The adapter marks backend rows unavailable from quota/configuration decisions and attaches sanitized routing metadata without copying raw endpoint URLs, installed model names, API key material, or account identifiers. primr doctornow includes a sanitized provider-availability section built from the same generic snapshots. It reports configured cloud providers, absent keys, and local OpenAI-compatible availability without making paid provider calls or leaking local endpoint hostnames.
Fixed¶
- Provider availability metadata handling now tolerates malformed collector
values and sanitizes host-like labels, unsafe env names, quota-source strings,
and model-count values before they reach routing metadata or
primr doctor. - Citation normalization no longer emits a duplicate
## Sourcessection when the existing appendix carries a stray non-citation line (an access-date note, a titled entry). The appendix is now replaced whenever it runs to the end of the document, while a sources-style heading followed by a real section is left untouched so no trailing content is lost. - Final-cleanup blank-line collapsing now tolerates CRLF, so a CRLF-sourced report no longer ships runs of excess blank lines.
Security¶
- Hardened provider-availability sanitization after an adversarial review.
The duplicated sanitizer logic in
capability_routing.pyandcli_doctor.pyis now a single shared seam (ai/availability_sanitize.py), and three bypasses are closed: a quota-window label is now sanitized before it can carry a raw URL or account detail into routing metadata; code/error sanitization is ASCII-only so homoglyph or accented host text can no longer survivestr.isalnum(); the display-label guard rejects a dotted host/IP even when surrounded by spaces; and model counts are clamped so a crafted snapshot cannot print a pathologically large integer. The invariant is pinned by a dedicated sanitizer test suite plus a routing-metadata regression test.
[1.33.4] - 2026-06-25¶
Added¶
- Backend-freedom availability now includes generic collectors for user-owned
runtime capacity: cloud providers report non-secret configuration status, and
local OpenAI-compatible services are probed through the existing
operator-configured
/v1/modelspath. The snapshots intentionally avoid API key values, raw endpoint URLs, account ids, and installed model names.
Changed¶
- The provider-expansion roadmap now requires provider-by-provider prompt caching research, estimator support for cache write/read pricing, usage accounting, and explicit safeguards before any new Anthropic/OpenAI/Gemini/xAI or gateway caching controls can ship. No background pre-warming, paid keepalive refresh loops, or 1-hour TTL defaults are allowed.
[1.33.3] - 2026-06-25¶
Added¶
- MCP tool calls now write a privacy-preserving JSONL audit log with timestamp,
transport, tool name, hashed caller id, granted scopes, argument/result
hashes, approval token id, cost metadata, job id, duration, and outcome. The
new
primr://agent/audit/recentresource exposes recent events to local stdio callers and admin-scoped HTTP callers without storing raw tool arguments, raw results, or approval tokens. - Backend-freedom availability now has a pure quota-headroom contract: normalized quota windows, binding-window selection, elapsed-reset handling, stale last-known-good snapshots, and deterministic provider ranking. The contract is covered by unit tests and ready for live provider quota/status collectors to feed into the capability router.
[1.33.2] - 2026-06-25¶
Added¶
- MCP estimate tools now return signed, short-lived, single-use approval tokens
for the matching cost-governed execution tools. When server-side MCP cost-cap
enforcement is active,
research_company,generate_strategy, andgenerate_skill_packrequire bothmax_estimated_cost_usdand a matchingapproval_token, blocking approve-one-shape execute-another swaps and token replay.
Fixed¶
- Release publishing now builds and extracts GitHub release notes under Python 3.12, matching the package's declared supported floor. A release-integrity test pins that the PyPI workflow cannot drift back to Python 3.11.
- PyPI metadata now relies on the modern
Apache-2.0SPDX license expression and avoids deprecated license classifiers, so the old MIT classifier cannot reappear.
[1.33.1] - 2026-06-22¶
Fixed¶
- The circuit breaker (
utils/circuit_breaker.py) is now thread-safe: per-key state, failure/success counts, and state transitions are guarded by a re-entrant lock, and state-change listeners are notified outside the lock (so a listener can re-enter the breaker without deadlocking). Previously the lock-free read-modify-write could lose failure-count updates under the parallel section-writing and strategy pools, skewing failover/quota bookkeeping.docs/CONCURRENCY.mdupdated to match.
[1.33.0] - 2026-06-21¶
Changed¶
-
Relicensed from MIT to the Apache License 2.0 (OSI open-source). Free to use, build on, fork, and share.
pyproject.tomlandCITATION.cffdeclare the SPDX identifierApache-2.0. -
--budgetnow also bounds the cross-validation phase (Phase 5). Section enrichment (a web-search batch plus a regeneration call per weak section) and the contradiction-resolution call are skipped once the run budget ceiling is reached, so an active budget caps optional quality-polish spend instead of only the research-deepening (Phase 2) and strategy (Phase 6) stages. The assembled report still ships. --budgetis also rechecked between strategy documents in Phase 6, so a multi-strategy run (multiple--strategy-typevalues) stops generating once the ceiling is reached instead of producing every requested strategy. Strategies already generated still ship.
Fixed¶
- Bug-hunt round: final-report cleanup no longer silently deletes legitimate
confidence-labeled external sources. The internal-source-placeholder stripper
matched broad lowercase substrings ("market analysis", "company report",
"industry baseline"), so a real citation like
[Reported: per Gartner market analysis]was removed whole; only primr's own internal artifact names are stripped now. - Bug-hunt round: the citation-integrity and section-structure ship gates now
ignore fenced code blocks, so a
[cite: N]or## headingshown as example syntax inside a code fence can no longer false-block the polished DOCX. - Bug-hunt round: EDGAR company lookup no longer mis-resolves a short company name to a wrong CIK when a ticker-index title normalizes to an empty string.
- Bug-hunt round:
primr skills --from-plannow raises the documented helpful error (instead of a rawAttributeError) when a hand-edited role plan contains a non-object role entry or non-objectevidence. - Bug-hunt round 2: final-report cleanup no longer collapses leading indentation. The interior-space cleanup previously flattened nested lists and broke fenced/indented code blocks in shipped reports; it now preserves leading indentation and skips fenced code entirely.
- Bug-hunt round 2: citation deduplication no longer treats
refandsourcequery parameters as tracking noise, so two genuinely distinct sources that differ only by?ref=/?source=are no longer collapsed into one citation (which silently dropped a real source). Unambiguous tracking params (utm_*,*clid,_ga, etc.) are still stripped. - Bug-hunt round 2: markdown links whose URL contains balanced parentheses
(e.g. a Wikipedia
..._(company)link) are no longer truncated at the first), which had corrupted the stored source URL and left a stray)in prose. - Bug-hunt round 3: strategy citation normalization no longer truncates the
document at the first heading named
## Sources/## Citations/## References. A body section legitimately titled "References" used to delete itself and every following section; only a real trailing citation appendix is replaced now. - Bug-hunt round 3: strategy artifact repair no longer truncates its input to 50K characters, which silently dropped everything past 50K from the repaired document. The full document is sent to the repair step.
- Bug-hunt round 3: DOCX rendering no longer mis-detects a heading or bullet
that merely contains a
|as a table (which rendered it as plain text with literal##/-markers); a markdown|---|separator row is now required. Parenthesized URLs render without truncation, and5*3-style math is no longer mis-italicized.
[1.32.8] - 2026-06-20¶
Added¶
primr skillsnow accepts--from-jd PATHto add a local job description or role brief as sanitized hiring evidence. The JD is materialized at_hiring/operator_role_brief.md, prepended ahead of scraped hiring summaries, and used by both role planning and authoring. MCPestimate_skill_pack/generate_skill_packmirror the samefrom_jd_pathinput.primr skillsrole planning now records a non-blockingposting-incompletewarning when observed postings for a mid-market-or-larger organization cluster in one narrow band. The warning appears inrole_plan.mdand the pack report with recommended operator curation paths.- Cowork skill-pack packaging now enforces the current Microsoft 365 Copilot
Cowork plugin limits locally: max 20
agentSkillsin the sideload manifest, max 1 MB perSKILL.md, and companion files capped at 20 files / 5 MB each / 10 MB total per skill. Larger packs still emit the full unpacked tree while the Cowork zip contains the first valid 20-skill slice. - Raised transitive dependency security floors for
msgpackandpydantic-settingsso CI and downstream installs resolve past newly publishedpip-auditadvisories. primr skillsnow accepts repeatable--career-url URLinputs and MCPcareer_urlsto collect exact segmented career / ATS boards as hiring evidence. Direct ATS URLs are parsed with the provider adapters, vanity career pages can resolve through redirects, and valid board slices are merged before role planning.- Skill packs now include curated archetypes for common business functions: sales, marketing, people operations, finance, legal/compliance, and operations. Weak display-name matches no longer produce usable archetype grounding, preventing business roles from inheriting unrelated technical templates.
Changed¶
- Modernized package license metadata to the SPDX-style
license = "MIT"form and raised the build backend floor tosetuptools>=77.0, removing the release-build deprecation warning before it becomes unsupported. primr skillsnow emits clean Agent Skills frontmatter by default (name+descriptiononly). The primr-namespaced handoff metadata remains available through the CLI--emit-agent-metadataflag, the MCPemit_agent_metadataargument, orSkillPackConfig(emit_agent_metadata=True).- Skill authoring now bakes in stronger hand-built-skill patterns: intake
prompts, explicit scope guardrails, human checkpoints, and worked
input/output examples. Bodies under 300 words are now ship-blocking hard
findings, and missing quality markers produce a hard
BODY-QUALITYfinding that refinement must repair before packaging. - Skill packs now attach a deterministic
references/role-family.mdfile to every skill in the same role family. The reference is built once from sanitized role evidence and archetype grounding so shared role context stays consistent across skills instead of being independently authored per skill. primr skillsnow treats generated files explicitly as draft skills with a tighter house structure: exactly three body sections, required input and produced-output markers, no extra report/background H2 sections, and a 300-1500 word target. Authoring and refinement prompts now use company context to make workflows, inputs, outputs, and validation concrete rather than turning the skill body into a context summary.
Fixed¶
- Removed visible generator attribution from generated Cowork manifests, role plans, and skill-pack reports so sideloaded skill packs do not show a tool-branded developer label.
[1.32.7] - 2026-06-17¶
Changed¶
- Clarified the backend-freedom cost policy: default routing should prefer billing-proven zero-incremental host or validated local capacity when configured, otherwise the best sub-dollar API recipe, with premium routes kept explicit and justified by measured lift.
- Expanded the host-runner roadmap language beyond Codex and Claude Code to include Kiro CLI, Copilot Cowork, Claude/Cowork-style hosts, and comparable official agent surfaces as candidates for bounded stage runners. Public promotion also requires billing provenance or an explicit potentially metered billing acknowledgment.
- Clarified that local inference is a moving first-class path: today's local quality label is tied to measured hardware/model profiles, and future desk-side AI capacity should be re-evaluated for $0 API default promotion.
- Added a focused
4090-report-racelocal eval shortlist and documented the RTX 4090 path as a concrete$0 API vs sub-dollar APIvalidation track.
[1.32.6] - 2026-06-17¶
Added¶
- Added a pure capability routing layer for stage-level backend selection:
StageRequirements, backend capability rows, inference profiles, billing policy checks, ordered route plans, and explicit rejection reasons. The first slice is side-effect-free and covered by fake backends so backend-freedom work can progress without live LLM spend.
Fixed¶
- Hardened the OpenClaw TypeScript adapter tests so CI resolves
tsxthroughnpx --yesbefore adapter assertions and uses a CI-realistic timeout for the TypeScript runner.
[1.32.5] - 2026-06-17¶
Added¶
- Added a transport-free host-agent runner seam for official host execution: bounded stage packets, explicit billing policy, evidence fencing, normalized runner metadata, and fake-runner tests. Authentication alone does not establish plan-backed billing.
- Documented the host-runner boundary for Codex and Claude Code style surfaces:
official automation only, billing provenance or explicit acknowledgment before
public promotion, no browser-session scraping, and no unofficial subscription
proxies.
primr-zerois the supported plan-native path.
Fixed¶
- MCP doctor now recognizes XAI, Gemini/Google, OpenAI, and Anthropic direct provider keys instead of reporting only Gemini-style credentials as configured.
[1.32.4] - 2026-06-17¶
Security¶
- Provider-hosted image URLs returned by remote image-generation APIs are now SSRF-checked before fetching and checked again after redirects; oversized image responses are rejected before resize.
- Google grounding redirect fallback decoding no longer accepts unsafe decoded internal/metadata URLs, and the block log avoids printing the decoded URL.
- Skill output path containment now uses path-aware ancestry checks instead of string-prefix checks, closing sibling-prefix escape cases in both the skill-pack Claude tree writer and the legacy skills-ideation writer.
- Outbound
HEADrequests, AI preflight website checks, and Wayback CDX/replay fetches now run the shared SSRF guard before network access and validate the final URL after redirects. - Invalid or out-of-range URL ports are now rejected as validation errors instead
of raising through lazy
urllibparsing, and MCP SSRF rejection logs redact URL credentials, query strings, and fragments.
Fixed¶
- Website preflight still reports ordinary DNS failures as reachability warnings instead of turning them into unsafe-URL blocks.
[1.32.3] - 2026-06-17¶
Changed¶
- Cleaned up README, ROADMAP, and artifact-guide drift around standard-run estimates, Gemini/XAI key roles, skill-pack cost, best-effort PDF output, roadmap changelog freshness, provider opt-in setup, and current coverage/test-count wording.
Fixed¶
primr doctorand the config validator no longer treat Gemini as the only acceptable cloud LLM provider key. OpenAI-only and Anthropic-only setups now pass the provider-key layer and are left to the provider registry for SDK usability checks.- Dry-run estimates now auto-select the provider-routed standard estimate for
OpenAI-only and Anthropic-only key setups, price the utility bucket through
Role.UTILITY, and label routed estimates without stale Grok/Gemini premium wording. - Full-run preflight now allows XAI-only standard execution, while OpenAI-only and Anthropic-only full-report runs fail fast with an explicit backend-freedom roadmap message instead of implying that execution path is already complete.
[1.32.2] - 2026-06-16¶
Fixed¶
A bug-hunt round across the security, scraping, AI, output, QA, and core layers (CodeQL and OpenSSF Scorecard were clean of code findings; these came from a manual audit). All fixes ship with regression tests.
- SSRF validator crashed on an out-of-range port.
is_safe_urllet the lazyurllibparsed.portValueError(e.g.:99999) propagate instead of returning(False, reason)- on the untrusted post-redirect path. Now guarded. - Modern OpenAI keys were not redacted in logs. The secret-masking pattern
only matched the classic 48-char form;
sk-proj-/sk-svcacct-/sk-admin-keys slipped through. Broadened to cover the prefixed/variable-length forms. - Numeric-IP SSRF backstop bypassed by a trailing dot.
127.0.0.1.skipped the platform-independent decoder and fell back to the OS resolver. Fixed. - Cross-provider utility LLM calls were dropped from cost accounting.
llm()'s OpenAI/Anthropic/Ollama dispatch returned without mirroring usage, so those tokens never reached the run cost summary or the budget gate. --budgetcheckpoint consolidated into a sharedskip_stage_if_over_budgethelper (fast mode now uses it;would_exceed/exceededboundary aligned to>=). Wiring the same runtime gate into the standard/premium AI-strategy stage is deferred to the trackedresearch_agent.pysplit (it is at its pinned line ceiling); a--premium --budget Nrun stays bounded by the pre-flight estimate gate until then.- Anthropic response parsing crashed on a leading non-text block. With
thinkingenabled,content[0].texthit a thinking block. Now concatenates text blocks only. - DOCX tables rendered a spurious
---row. The separator regex omitted the inner|, so multi-column separators were rendered as data. - Citation grade was zeroed for
## Sources Consulted-style headings. The bibliography matcher required an exact heading; loosened to allow trailing words. - Vision tier referenced a non-existent
ErrorType.EMPTY_CONTENT, turning an insufficient-content result into a swallowedAttributeError. Enum member added. - Scraping smart-stop under-counted consecutive failures because
last_error_typemixedErrorTypeenums and strings; normalized to one key. is_invalid_api_key_errorover-matched ("Invalid argument" → treated as a bad key and aborted the run). Tightened to auth-specific phrases.--budgetboundary inconsistency:would_exceedused>whileexceededused>=; aligned to>=.- Resume reported failure despite finalized jobs: a transient check error on one job no longer masks others that completed.
- CSV-injection sanitizer missed leading-whitespace/newline payloads
(
=cmd); now checks the first non-whitespace character. - Dependency security floor:
azure-identity>=1.16.1(GHSA-m5vv-6r4h-3vj9, elevation of privilege) - flagged by Scorecard's OSV scan against the floor.
[1.32.1] - 2026-06-16¶
Security¶
- Dependency security floors raised for three June 16 2026 advisories. Trivy and pip-audit flagged HIGH-severity vulnerabilities in dependencies that touch the MCP/A2A/API server surface; floors are now pinned so no install path can resolve to a vulnerable version:
starlette>=1.3.1(was>=0.27.0) - CVE-2026-54282/54283: form-parsing limits silently ignored, enabling denial of service.python-multipart>=0.0.31(newly pinned) - CVE-2026-53538/53539/53540: quadratic-time querystring parsing causes CPU denial of service.cryptography>=48.0.1(newly pinned) - GHSA-537c-gmf6-5ccf: vulnerable OpenSSL bundled in the affected wheels.- Lockfile resolves to
starlette1.3.1,python-multipart0.0.32, andcryptography49.0.0. No source changes; full suite green.
[1.32.0] - 2026-06-14¶
Context engineering (flag-gated, eval-pending)¶
- Relevance-ranked section evidence (
PRIMR_SECTION_EVIDENCE_CURATION=1). The section writer's evidence subset was a blind first-100k-chars truncation of the scraped corpus, shared across sections. Newcore/context_curation.pyrank_corpus_by_relevance()instead keeps the most-relevant 100k - corpus[Page:]blocks ranked by term-overlap with the analysis workbook (which already distilled the run's themes) - so the budget is spent on signal, not scrape order. Shared across sections (preserves the cached prompt prefix from the #8 split); deterministic and dependency-free; conservative fallbacks (no page markers / empty reference / corpus within budget → prior behavior). It is context assembly (a relevance rank), not a content gate, and its effect is eval-gated (docs/design/eval-plan.mdEval 4): default off is byte-identical, so this ships as an opt-in to be validated by an A/B before any default change. - Evaluated (n=1, ~$1.4): WASH - stays default-off. A/B on a large content-dense company (corpus ~360k chars, so curation dropped ~72%): blind pairwise grade tied on every section. Relevance-ranking the corpus subset doesn't change brief quality even when it fires hard. Combined with the Step 4 result, this shows quality isn't bottlenecked by which evidence reaches the writer - it rides on the workbook + writer prompts. The feature stays merged but off (no harm; a seam for a future per-section-routing version). Next real quality lever: the analysis/section prompts (content depth, #4), not plumbing.
Artifact shipping - de-brittle (content gates become signals)¶
- Leaked-label scan no longer false-blocks legitimate lowercase prose. The
forbidden-output scan ran case-insensitively, so a report saying "based on our
internal analysis" or "in the analysis context of X" was blocked from shipping
because it matched the internal workbook labels
Internal Analysis/Analysis Context/Internal ROI Model. Those labels now match case-sensitively (a new_FORBIDDEN_LEAKED_LABELSset), so only the exact Title-Case leaked form is caught and ordinary lowercase content ships untouched. The bracketed/filename tokens ([Source:],vendor-research-*.txt, ...) stay case-insensitive - their delimiters never occur in prose, so they can't false-block. (agentic-balance: don't gate real content.) - Scaffolding-leak detection is now a non-blocking warning, not a ship gate.
A leaked internal marker (
[workbook], bold**What to validate:**, informal[cite: label]) no longer withholds the polished DOCX; it is surfaced (logged) and eval-tracked (## Artifact Drift) while the deliverable ships. A regex cannot be a quality moat - content quality is enforced upstream (the writer prompt) and measured by eval, per the standing rule indocs/design/agentic-balance.md. Blocking is reserved for what a rule can legitimately judge: structural/referential validity (citation resolution, duplicate/empty sections) and unambiguous internal-token leaks (raw[Source:]/[Workbook:])._validate_output_markdowngains awarningsfield; the regression corpus asserts the scaffolding fixture ships with a warning instead of being blocked.
Provider setup¶
primr keys setnow covers every wired provider. The OpenAI and Anthropic providers were wired inai.providers(andprimr doctorlists them), butprimr keys set anthropic/openaifailed with "Unknown key" because the key-alias map had drifted. Addedanthropic/claudeandopenai/gptaliases (so the keys also show inprimr keys list), plus a test pinning that the keys surface never drifts from the provider registry again.
Security¶
- Platform-independent SSRF guard for obfuscated numeric IPs. The SSRF guard
now canonicalizes octal / hex / decimal / short-form IPv4 literals itself
(e.g.
0177.0.0.1,0x7f.0.0.1,2130706433,127.1) and blocks those resolving to loopback/private/reserved/metadata, instead of trusting the OS resolver (whose decoding varies - macOS does not decode octal dotted-quad). Applied as an additive backstop inis_safe_urland the MCPURLValidator.
Machine-readable output¶
--jsonfor scripting and agents.primr <co> <url> --jsonemits a single JSON result summary (status, report/DOCX paths, word count) to stdout;primr <co> <url> --dry-run --jsonemits the cost estimate as JSON (estimate-first).--jsonimplies quiet so progress chrome never interleaves with the JSON. (primr recon --jsonalready existed.)
CLI robustness¶
- Actionable errors instead of raw tracebacks. An unexpected failure that
reaches the top of the CLI now prints a short message that routes you to
primr doctor, offers--verbosefor the full traceback, and links the issue tracker, rather than dumping a stack trace. Ctrl-C exits cleanly (code 130, "Cancelled") instead of aKeyboardInterrupttraceback. - Shell tab completion (opt-in). If
argcompleteis installed,primroffers tab completion for its subcommands and flags; enable it withactivate-global-python-argcomplete(orregister-python-argcomplete primr). Withargcompleteabsent it is a no-op, so it adds no dependency.
Research framing (tradecraft Step 1)¶
- Operator framing now shapes the analysis, not just the strategy appendix.
A new
ResearchFraming(purpose, audience, the decision it informs, the core question, plus discovery notes) is resolved once and threaded into the analysis workbook and every section prompt. Previously--discovery-notesreached only the final strategy stage. New flags:--purpose(general/sales_pursuit/diligence/competitive_intel/partnership),--audience,--decision,--question. Unframed runs are unchanged: framing renders to an empty prompt block, so prompts stay byte-identical (and the cached section-prompt prefix stays cacheable). Seedocs/design/research-tradecraft.md. - Day-1 hypothesis tree (Step 2). When a run is framed, primr forms a MECE
issue tree of build-to-refute hypotheses from the cheap signal layer before
the analysis workbook, writes it as an inspectable
hypothesis_tree.{md,json}artifact, and prepends it so the workbook is hypothesis-driven. Unframed runs are unchanged (no extra cost). Using the tree to steer collection is a later step. --plancheckpoint (Step 3).primr <co> <url> --planpreviews the framing, the Day-1 hypothesis tree (from free DNS recon + the cheap signal layer), and the proposed report outline, writesplan.md+hypothesis_tree.{md,json}to the working folder, and exits before any expensive collection or writing - a pre-run alignment step (no spend beyond a cheap Day-1 pass).- Budget-aware research deepening (tradecraft Step 4). Research
deepening (gap analysis + extra searches/scrapes) is an optional spend stage,
so it now honors an active
--budget: when actual LLM spend has already reached the ceiling, deepening is skipped and the report ships with the sources already collected, recorded ingap_analysis.mdrather than silently dropped. Mirrors the Phase-6 strategy checkpoint - the irreversible act (spend) is gated, never the reasoning. This is the budget gateagentic-balance.mdcalls the prerequisite for going agentic on collection. - Hypothesis-steered gap analysis (tradecraft Step 4). On a framed run the Day-1 hypothesis tree is now built once before the deepening stage and threaded into gap analysis, so the extra searches test under-evidenced branches ("which working hypothesis is unproven, and what evidence would confirm or refute it") instead of filling generic data gaps. The same tree is reused by the analysis workbook instead of being rebuilt. This is a prompt-level change (judgment, upstream) with the GAP/QUERY/PRIORITY output contract unchanged; unframed runs keep a byte-identical gap prompt and form no tree.
Install / update quality-of-life¶
primr update- self-upgrade to the latest PyPI release; detects pipx vs pip and runs the right command, reporting before/after version.primr update --checkchecks without installing;-yskips the prompt.- Passive update notice - a one-line "update available" hint after a
successful research run and in
primr doctor. Cached ~24h in the per-user dir, fail-safe (never blocks a run), opt-out viaPRIMR_NO_UPDATE_CHECK. Usesrequests(already a core dep) - bandit-clean, no new dependency. - Idempotent installers -
scripts/install.{ps1,sh}now upgrade an existing install on re-run, verify the result, and surfaceprimr update.
Engineering: anti-slop development contract + fitness gates¶
CLAUDE.mdcommitted at the repo root as the canonical development contract (un-ignored from.gitignore): the single seams to use, the no-new-giant-file rule, the verify-current-APIs rule, the CLI verb convention, and the pre-PR slop check. Distinct fromAGENTS.md, which stays the operate-primr product guide (a disambiguation header now points dev-agents toCLAUDE.md);CONTRIBUTING.mdreferences it. Follows the June-2026CLAUDE.md/AGENTS.mdsplit (Claude Code readsCLAUDE.mdnatively;AGENTS.mdis the cross-tool standard). The contract also conforms to the repo's own context-map schema, activating six previously-dormanttest_context_map_*property tests (they skipped while noCLAUDE.mdwas committed): required sections, negative constraints, verification commands, progressive disclosure, and the Quick Start token budget.tests/test_architecture.py- deterministic architectural fitness suite: a rise-only per-file line ceiling (14 files >1,000 lines pinned and blocked from growing; new files cap at 1,000), a single-JSON-library gate (stdlibjsononly), and an agent-contract-exists check. Design doc:docs/design/engineering-excellence.md.- Two monster files split to hold the line ceiling (no behavior change).
The June-13 registry audit pushed
config/models.pypast its ceiling, so the ~760-lineModelRegistrydata block (the part you edit when a provider ships or retires a model) moved to a newconfig/model_registry.pyand is re-exported fromconfig/models.py- everyfrom primr.config.models import ModelRegistry/ModelConfig/ModelType/GrokTierkeeps working, and adding model entries no longer trips the ratchet. Thekeyssubcommand handler (_create_keys_parser+_run_keys, ~130 lines) moved out ofcore/cli.pyintocore/cli_keys.py(create_keys_parser/run_keys), matching the existingcli_doctor/cli_batchextraction pattern (Active Queue #23).
Design docs¶
- Decision: report section structure stays a curated rule (tradecraft Step 5
descoped). A strategic brief's shape is a known, stable thing - consistency
is a feature of a deliverable, and per-run structural variability trades
reliability for "rolling the dice." The
company_overview.yamlscaffold is researched/iterated offline, not re-derived per run; by Principle 1 it does not demonstrably fall short, so it stays a rule. The agentic judgment for #4 lives in the content within sections (depth, insight, Pyramid "so what", constrained-evidence reasoning), not in choosing sections. Recorded inagentic-balance.md(structure carve-out),research-tradecraft.md(Step 5), and ROADMAP #4. docs/design/research-tradecraft.md- plan to shift the pipeline's collection and analysis from collection-first to hypothesis-first (framing, Day-1 hypothesis tree, plan checkpoint), keeping the deliverable structure a curated scaffold.docs/design/eval-plan.md- pre-registered, cheapest-first plan for the pending paid evals (label-calibration baseline ~$0.10, framed-vs-unframed ~$1.58/co, content-depth ~$4-5/co) with exact commands, instruments, and go/no-go acceptance criteria, so a paid run yields a decision, not a vibe.- Eval result - tradecraft Step 4 (framed-vs-unframed) = NO-GO for default (~$0.69 spent, n=1). First paid A/B confirmed the hypothesis-steering fires correctly but produced no quality lift (blind pairwise wash, slightly favoring unframed) at neutral cost - steered collection trades breadth for depth and fights the broad fixed structure. Step 4 stays opt-in; not promoted; no further collection-steering built on it. The label-calibration baseline also ran (~$0.00) and flagged low label-traceability worth re-measuring at scale. Next candidate lever recorded: context curation at the analysis/writing stage (the ~1.9M-token prompts are the real bottleneck), not more collection-steering.
- Eval finding - epistemic grounding is the one real quality lever (~$2.17
total spend across all evals). Label-calibration at scale (3 reports, incl.
large content-dense briefs with 25+ "Reported" claims): Confirmed 8% / Reported
0% source-traceability (
unfetchable=0- sources fetched, claims didn't trace). Combined with the two wash results (collection-steering, context-curation) and a direct read confirming the prose is already consultant-grade, the data-backed map is: prose strong, evidence-plumbing exhausted, grounding systemically deficient. The next quality work is a label-honesty pass (verify each claim against its source, downgrade ungrounded labels - like--verify), validated for ~$0 via calibration on existing reports. Recorded ineval-plan.mdEval 1. docs/design/agentic-balance.md- the standing rule-vs-judgment decision aid (primr targets NVIDIA "Level 2": deterministic control flow, model judgment at fixed decision points). Now spells out the failure mode in both directions - brittle content rules (regex gating quality) are a documented FAIL driver, grounded in June-2026 sources (Microsoft red-team taxonomy, the eval-layering guides) - and the litmus test for which side of the line a change sits on. The ROADMAP header now routes every "add a rule or go agentic" decision through this doc and asks contributors to keep it current.docs/design/engineering-excellence.md- anti-slop enforcement plan.
[1.29.2] - 2026-06-05¶
Skill pack - hardening (post-1.29.1 code review)¶
behavioral_eval.grade_output: strict verdict coercion - string verdicts like "false"/"no"/"0" no longer count as passes (every non-empty string is truthy in Python), and grader length-mismatch is logged instead of silently skewing the with/baseline delta.refiner.auto_resolve_overlaps: revert decision now compares HARD finding identity, not count - a re-scope that swaps one HARD finding for a different one is correctly reverted.validator: removed generic words (front/door/functions) from the NAME-PRODUCT brand set (false-flagged task names likefront-desk-triage); DESC-PUSHY intent counter no longer splits on "and" (which over-counted and let thin descriptions pass); SEC-INJECT patterns tightened so benign domain prose ("ignore previously assigned licenses", "run the scripts/x.py helper") no longer trips the injection guard while real injection is still caught.planner._merge_and_cap: plausible roles are deduped against the archetypes of KEPT observed roles only, so a reserved business-function slot is not lost to an observed role the reserve bumps to gap.authoring._parse_bundled_files: the double-escaped-\nnormalization runs only for markdown references, never forscripts/*.py/evals/*.jsonwhere a literal backslash-n is meaningful.pipeline: failing roles are now dropped BEFORE the opt-in trigger/behavioral passes, so no LLM budget is spent on roles that are then discarded.packager: a shared folder-slug safety check guards both the Claude tree and the Cowork zip against path traversal.- New
tests/test_no_brand_leak.pyCI guard fails the build if a denylisted real-company / third-party brand token appears insrc/ortests/.
[1.29.1] - 2026-06-05¶
Supersedes 1.29.0 (yanked): removed an inadvertent third-party product name from internal test fixtures and one prompt example. No functional change.
Skill pack - four-tier quality overhaul¶
A staged refinement of the skill-pack pipeline that closes most of the gap against Anthropic's skill-creator workflow (see ROADMAP #15). Tiers 1 and 3 are on by default at no extra LLM cost; Tiers 2 and 4 are opt-in measured proof loops behind CLI flags.
Tier 1 - roster + authoring quality (default, no added cost):
- Holistic rosters.
plan_plausible_roles.yamlnow produces a roster spanning BOTH the company-specific named practices/services (highest priority - a flagship branded offering named in the research always earns a role) AND the universal functions every Mid-market+ org runs (Sales, Marketing, Customer Success, HR/People, Operations, Finance, Legal/Compliance, IT)._merge_and_capreserves a fraction of the roster (PLAUSIBLE_RESERVE_FRACTION, default 0.4) for plausible org-shape roles so a one-function posting set can't crowd them out; observed (posting) roles still take the leading slots and win ties, and reserve-displaced observed roles flow togap_flaggedrather than being silently dropped. - Task-named skills, not product names.
author_skill.yamlforbids bare product/feature titles (azure-front-door,aks); the skill names the capability the product is used for (configuring-edge-traffic-routing), product in the body. New SOFT validatorNAME-PRODUCTflags violations. DESC-PUSHYcounts trigger intents, not keywords. Previously counted hits from a fixed verb lexicon and false-flagged well-formed enumerations using verbs outside the list (perform / prepare / conduct). Now counts the distinct enumerated intents after the trigger phrase, broadened verb set as a fallback only.- Thin bodies are refined, not just flagged.
refine_roletreats a too-short body (under the 150-word floor) as an actionable finding worth one expansion turn; the authoring prompt states the minimum with "add a worked example, don't pad" guidance. - Cross-role overlaps are auto-resolved.
auto_resolve_overlapsre-scopes one skill of eachPACK-OVERLAP-LLM/PACK-TRIGGERpair (conservative: only the second is touched, reverted if it gains a HARD finding) instead of only reporting them. ToggleSkillPackConfig.auto_resolve_overlaps.
Tier 2 - measured trigger optimization (--optimize-triggers, opt-in):
- New
skill_pack/trigger_eval.py: per skill, generate should/should-not- trigger queries, score the description against a blind discovery simulator, and rewrite it when below threshold - kept only if it beats the original on a held-out split. The rigorous replacement for theDESC-PUSHYheuristic (Anthropic's published description-optimization loop). Results in the report.
Tier 3 - progressive disclosure (default):
- Skills can ship bundled resources alongside
SKILL.md:references/*.md(load-on-demand deep material) andscripts/*.py(deterministic helpers - "solve, don't punt"). NewBundledFileon theSkillschema; authoring may emit them; the packager writes them to both the Claude tree and the Cowork.zip.BUNDLE-PATHvalidates paths (references/*.md,scripts/*.py,evals/*.json, single subdir, no traversal); unsafe paths dropped.
Tier 4 - behavioral evaluation (--with-evals, opt-in):
- New
skill_pack/behavioral_eval.py: per skill, generate task cases + objective assertions, run each task WITH the skill vs WITHOUT, grade both blind, and report the with-skill-vs-baseline pass-rate delta - proving the skill changes output, not just that it is well-formed. Also writesevals/evals.jsonper skill (Anthropic's published structure). Expensive, so gated and off by default. Results surfaced in the pack report.
[1.28.0] - 2026-06-02¶
Artifact pipeline - prompt hardening (Active Queue #2 closed)¶
- Writer and regeneration prompts now explicitly forbid the internal-scaffolding
markers the ship-time gate strips (
[workbook]/[Analysis Workbook],[cross-ref ...]/[see ## ...], informal[cite: label], bold**What to validate:**), sourced from a singleqa.report_analyzer.SCAFFOLDING_PROHIBITION_GUIDANCEconstant co-located withscan_scaffolding_leakageso the upstream instruction and the downstream gate cannot drift. Spliced into bothsection_prompts.pywriters and bothresearch_agent.pyregenerators (the strategy regenerator also gained the plain-text "What to validate:" rule). Parity locked by a deterministic test; runtime tracked bywriter_output_clean(_shipping_repair.json) + the eval## Artifact Driftmetric.
Verified page access - first-party RSS/Atom feed recovery (Active Queue #3)¶
fallback_sources.fetch_feed_contentadds the host's own RSS/Atom feeds as a first-class source in the blocked-origin fallback fan-out - HTML<link rel="alternate">autodiscovery + common-path sweep, same-site-filtered (defense-in-depth on the SSRF guard), RSS 2.0 / Atom / RSS 1.0-RDF parsed namespace-agnostically withdefusedxml(untrusted-XML safe; 5 MB body cap; no new dependency),content:encodedpreferred over short teasers, cross-feed item dedup. Wired intogather_fallback_contentassource="feed".
Test coverage + CI¶
- Global branch coverage 78.65% → 82.05%; CI ratchet raised 77 → 81. The
coverage job now installs the
a2aextra so the 165 a2a tests are counted, plus ~630 new unit tests acrossresearch_orchestrator,utils.security(incl. 100 adversarial SSRF cases - no vuln found),skill_pack.evidence,data.scrape,model_eval,mcp_server.{skill_pack_tools,server}, theagenticmodules,hiring_signals, thescrapinghelpers, andai_strategy. - Dependabot removed (
.github/dependabot.ymldeleted) in favor of manual review-and-bump backed by the pip-audit + Trivy hard gates. Applied the pending action bumps by hand:actions/checkoutv4→v6,actions/setup-pythonv5→v6,astral-sh/setup-uvv5→v7,actions/upload-artifactv4→v7,actions/download-artifactv4→v8.
Artifact pipeline hardening¶
- Scaffolding-leak shipping gate: the leak scan (bare
[workbook]/[cross-ref]refs, bold**What to validate:**lines, informal[cite: label]) was promoted from a QA warning to a configurable ship-time gate. Factored into the pureqa.report_analyzer.scan_scaffolding_leakage()and wired intooutput.artifact_validation._validate_output_markdown; leaks abovePRIMR_MAX_SCAFFOLDING_LEAKS(default 0) withhold the polished DOCX (MD/TXT + sidecar still written). Canonicalization runs upstream, so a healthy run sits at 0 and never trips - the gate only fires on a regression. Eval harness now tracksscaffolding_leaksper report +total_scaffolding_leaksper profile, surfaced in a scorecard## Artifact Driftsection and a CSV column. - Upstream cause of bold
What to validate:lines addressed: the section prompts now instruct the writer to emit that line as plain text (no bold/italics/bullet) in bothsection_prompts.pyOUTPUT CONTRACT blocks and theresearch_agent.pyregeneration prompt, reducing the rate the bold form is produced at all. - Citation-integrity shipping gate: new pure
qa.report_analyzer.scan_citation_integrity()flags inline[cite: N](incl. grouped[cite: 1, 2]) with no matching## Sourcesentry; wired into the same validator with a configurablePRIMR_MAX_DANGLING_CITATIONS(default 0). The deterministic backstop behind the upstream LLM citation repair, which keeps the original possibly-still-dangling report when it cannot reach zero. Covers report and strategy docs (both ship through the same validator). - Section-structure shipping gate: new pure
qa.report_analyzer.scan_section_structure()flags duplicate top-level##headings (merge/regeneration artifacts) and empty sections (a##heading with no body); wired into the same validator with a configurablePRIMR_MAX_STRUCTURE_DEFECTS(default 0). Required-section presence is deliberately not gated - it is report-type-dependent and too false-positive- prone to block shipping on; it stays a QA-scoring signal. Validated against the regression corpus so it does not false-block clean long-form reports. - Repair observability:
report_cleanup.compute_repair_report(before, after)(reusing the ship-time scaffolding scanner) measures how much the silent deterministic cleanup actually changed - scaffolding markers removed, chars stripped, and whether the raw writer output was already clean. Wired at the report cleanup seam to log a one-line summary and persist_shipping_repair.json. This is the measurement foundation for "push consistency upstream": thewriter_output_cleansignal makes the cleanup's load-bearing-vs-safety-net status trackable so prompt hardening can target the repairs that actually fire. - Artifact regression corpus:
tests/fixtures/artifacts/(placeholder companies) +manifest.jsonof expected gate outcomes, exercised by the data-driven harnesstests/test_output/test_artifact_corpus.py- which also renders the clean fixtures end-to-end throughmarkdown_to_docx+_validate_output_docx. A completeness test fails if a fixture is added without a manifest entry. Sanitized real artifacts can be dropped in later with no test-code changes.
Skill pack¶
- Agent-handoff metadata in
SKILL.mdfrontmatter: a primr-namespacedmetadatablock (role, provenance, confidence, an approximateprimr-context-tokensbudget, andprimr-refresh-via: mcp:primr/generate_skill_pack, a2a:primr) makes each generated skill self-describing to a consuming agent without inferring its capability/cost contract. Grounded entirely in pack data; on by default, opt out viaSkillPackConfig(emit_agent_metadata=False). - Fixed a latent Windows bug: the Claude-tree
SKILL.mdwas written viaPath.write_text(CRLF translation) while the Cowork zip used raw LF, so the documented "byte-identical SKILL.md" invariant silently broke on Windows. The Claude-tree write now usesnewline="\n"so it holds cross-platform.
Model eval wiring (Gemini 3.5 Flash PRO-tier decision)¶
- Registered a head-to-head eval pair in
config/eval_profiles.py-protier-gemini31pro(reference, Gemini 3.1 Pro writer) vsprotier-gemini35flash(candidate, Gemini 3.5 Flash writer) - isolating the quality-writer model so the scorecard can answer whether to repoint the PRO tier. The default pipeline is unchanged; the repoint is eval-gated and the run is billed/user-triggered (primr eval ... --profiles protier-gemini31pro protier-gemini35flash).
Supply-chain hardening¶
- Fixed a latent release-breaking bug: the dependency manifest was written
into
dist/, which the PyPI publish step uploads verbatim - twine would have rejected the non-distribution file and failed the next release. SBOM artifacts now go in a separatesbom/artifact, attached to the GitHub release but never to PyPI;dist/holds only the wheel + sdist. - CycloneDX SBOM: releases now ship a standard CycloneDX JSON SBOM
(
cyclonedx-py, invocation validated locally) alongside the pinned uv requirements manifest. - PEP 740 Sigstore attestations made explicit (
attestations: true) on the PyPI publish step (default-on for Trusted Publishing; pinned so it can't silently regress), complementing the existing SLSA build-provenance attestation. - Trivy supply-chain scan added to CI (filesystem vuln + misconfig, HIGH/CRITICAL, unfixed-ignored), now a hard gate - complements the pip-audit + bandit hard gates. It immediately earned its keep:
- Fixed (CRITICAL ×3):
openclaw/Dockerfile.primrdeclared secret API keys viaENV(bakes secret-named vars into image layers); removed - they are runtime-provided. - KSV-0118 resolved as a platform false-positive (corrected from the
initial triage): verified against the Cloud Run v1 YAML schema that
fully-managed Cloud Run does not expose a container
securityContext(the RunV1 type carries onlyrunAsUser, "Not supported by Cloud Run"), sorunAsNonRootis rejected bygcloud run ... replace- no manifest change can clear it. Non-root is already enforced by the image (deploy/Dockerfileopenclaw/Dockerfile.primrrunUSER primr, uid 1000). The.trivyignoreentry is now a permanent, doc-cited false-positive, pinned by a regression test (TestGCPSecurityContext) that forbids adding a deploy-breakingsecurityContext, with inline rationale in both manifests.
- With the baseline clean (Trivy exits 0 after the ignore), the scan was
promoted from signal-only to a hard gate (
continue-on-errorremoved).
Hygiene ratchets¶
- Removed deprecated
datetime.utcnow()across the codebase (deprecated in 3.12+, scheduled for removal; the project tests on 3.14). Newprimr.utils.timeutilsexposesutcnow()(timezone-aware) andutcnow_naive()(naive, behaviour-identical to the old call). The SQLite-backed monitoring / tenancy / knowledge-graph stores were migrated toutcnow_naive()on purpose: they persist offset-free ISO-8601 strings compared lexically in SQL, so an aware datetime would append+00:00and silently breakWHERE ts >= ?comparisons andfromisoformatround-trips against existing rows. Behaviour is byte-for-byte preserved; verified by running the affected suites with-W error::DeprecationWarning. - One-time
ruff formatreflow (173 files, behavior-preserving) andruff format --checknow enforced in pre-commit + CI.E501stays ignored deliberately (ruff format wraps code; remaining long lines are strings/URLs). - ruff
target-version→py312(matches the floor). Applied the surfacedUP035fix; deferred the PEP 695 generic rewrites (UP046/UP047) via documented ignores (TypeVar generics are correct; the bulk unsafe-rewrite isn't worth the risk now). - mypy config consolidated + strict ratchet made real:
mypy.iniis the authoritative config - the duplicate[tool.mypy]block inpyproject.tomlwas dead config that never took effect (and described a strict allowlist that wasn't applied); removed it and added a pointer. Bumpedpython_versionto 3.12 and added the first genuine strict allowlist (disallow_untyped_defs+disallow_incomplete_defs):skill_pack.{schema,config,planner,industry},utils.content_sanitizer,utils.logging_config,data.hiring_signals. - Complexity budget (
C901) remains deferred until the monster functions are refactored (Active Queue #23) - a meaningful cap would otherwise require noqa-ing the known offenders.
Verification ratchets¶
- Invariant property tests (Hypothesis) pinning the load-bearing correctness
invariants, chosen over the
deallibrary (no new dependency; fits the exception-based style): skill-pack roster-cap merge (tests/skill_pack/test_invariant_properties.py- partition, cap, observed priority, archetype-dedup-for-plausible, trim-priority order), the SSRF guard result shape (tests/security/test_invariant_properties.py- always(True, None)or(False, <non-empty>)), and theCostGuardHookbudget rule (tests/agentic/test_costguard_properties.py-remaining ≥ 0; BLOCK iffspent + max(0, estimate) > max_cost). The roster property test also sharpened the documented contract (observed-vs-observed archetype repeats are intentional; dedup applies to plausible roles only). - Stateful property test for the per-host tier circuit breaker
(
tests/test_data/test_scraping/test_circuit_breaker_stateful.py): aRuleBasedStateMachinedriving arbitrary attempt sequences and asserting failures ≤ attempts, any-success ⇒ never-skipped, skip ⇒ all-failures-past-threshold. - Fault-injection hardening: closed a real redaction gap surfaced by the
fault lens -
SecretMaskingFilternow also masks secrets inside exception tracebacks (exc_text), not just the log message. A secret raised in an exception and logged withexc_info=Trueno longer leaks to the log file.
AI / agent security posture¶
Completes the in-scope security work from docs/SECURITY.md (threat model
T1-T7). No change to research-pipeline behavior beyond defensive sanitization.
- Indirect prompt-injection hardening (T1): new
fence_untrusted()inutils/content_sanitizer.pysanitizes untrusted retrieved content and wraps it in an explicit "data, never instructions" fence. Applied at the previously unfenced external-content→prompt boundaries: insights extraction (data/insights_extractor.py), the Deep Research dossier + stage-1 website context (ai/deep_research.py), and operator discovery notes are now sanitized (prompts/composer.py). Backed bytests/security/test_prompt_injection_corpus.py. - Egress guardrails (T2/T6): locked the "no fetch bypasses
is_safe_url" invariant across all three egress helpers withtests/security/test_egress_guardrails.py(loopback / RFC1918 / link-local / cloud-metadata all refused, initial + post-redirect). - Chat-log secret redaction (T3):
utils/chat_logger.pynow runsmask_sensitive_dataover prompt + response before persisting and writes atomically (temp +os.replace); errors go through the logger, notprint. - Threat model (T1-T8):
docs/SECURITY.mdrewritten as a scoped MITRE-ATLAS threat model - explicitly declares model-training/serving security out of scope (primr owns no weights), documents per-threat control status + residual risk, and refreshes supported versions / disclosure. Linked from README + docs index. - Drive-by: fixed genuine pre-existing typing/dead-code nits in touched files
(
ContextVar[dict | None]annotation;.items()→.values()where keys unused).
Engineering standards & toolchain hardening¶
Infrastructure and supply-chain work; no runtime behavior change to the research pipeline. See ROADMAP "Engineering Standards & Toolchain" for the full plan.
- Python floor raised to 3.12 (
requires-python>=3.12, EOL-driven: 3.11 reaches EOL Oct 2027, 3.12 covered to Oct 2028). 3.11 dropped from classifiers, CI matrix, andsetup_env.pyinterpreter discovery. Breaking for 3.11-only users. CI now runs a3.12 / 3.13 / 3.14hard matrix - all fully supported (full suite passes on each; native-dep stack installs cleanly on 3.14). Free-threading (3.14t) remains a non-goal. - uv toolchain: committed
uv.lock+.python-version; CI installs viauv sync --frozen; setuptools build backend retained. Dependency lower bounds reconciled fromrequirements.txtintopyproject.toml. - Security gates in CI:
bandit(medium severity/confidence) andpip-auditnow block;.github/dependabot.yml(weekly pip + github-actions); SLSA build provenance attestation (actions/attest-build-provenance) + a pinned dependency manifest attached to each release (publishing already used OIDC). Fixed the findings that gate bandit rather than suppressing:hashlib.md5(..., usedforsecurity=False)for content-dedup hashing; untrusted sitemap XML parsing switched todefusedxml. - Coverage ratchet: measured global branch coverage 78%; CI gates at
--cov-branch --cov-fail-under=77(non-regression floor). - pre-commit (
.pre-commit-config.yaml): ruff + mypy + hygiene hooks (opt-in). xfail_strict = true: an unexpectedly-passing xfail fails the run (the suite uses zero xfail markers).
Model registry refresh (May 30, 2026 audit)¶
- Claude Opus 4.7 -> 4.8 (
claude-opus-4-8, GA May 28; identical $5/$25 pricing) - canonical Anthropic slug swapped repo-wide. - Gemini 3.5 Flash (
gemini-3.5-flash, GA May 19; $1.50/$9 + $0.15 cached) registered as available. Not a default: it's a PRO-tier replacement candidate (cheaper + stronger than 3.1 Pro), eval-gated. Default pipeline unchanged. Gemini 3.5 Pro (June) + Omni pending their API slugs.
[1.27.1] - 2026-05-29¶
Skill pack: operator roster curation¶
The v1.27.0 planning architecture decides "what roles should exist at this company" by analyzing job postings + research. Operators still need to override that decision when they know something the data doesn't show - augment with specific roles ("the discovered list misses Account Executive"), prune roles they don't want ("drop Marketing Manager"), or do both at once ("swap Marketing Manager for Demand Generation Manager"). v1.27.0 covered the binary cases (full override via --roles-override, accept-as-is via --from-plan) but had no augmentation surface - the only way to do partial curation was to hand-edit role_plan.json. v1.27.1 closes that gap.
Four-flag curation surface¶
--plan-only: run the planning step, writerole_plan.md+role_plan.json, exit before authoring (existing).--from-plan PATH: load a previously-persisted plan and skip planning (existing).--roles-add "A, B"(new): comma-separated list of role labels to APPEND to the discovered roster. Each label is materialized as aRolewithprovenance: override, archetype matching applied so authoring picks up the closest scaffolding.--roles-skip "X, Y"(new): comma-separated list of role labels or kebab-case slugs to REMOVE from the discovered roster. Match is exact, case-insensitive, against eitherdisplay_nameorname. Unmatched names log a warning so typos are visible.
The four compose:
- --from-plan PATH --roles-add "..." → load plan, append added roles, author the union
- --from-plan PATH --roles-skip "..." → load plan, drop skipped roles, author the rest
- --from-plan PATH --roles-add "..." --roles-skip "..." → load plan, drop skipped first, then append added
- --roles-add "..." alone → plan normally, append added before cap
- --roles-skip "..." alone → plan normally, drop skipped after merge
- --plan-only --roles-add ... --roles-skip ... → plan, apply curation, persist the curated plan, exit
- --roles-override "..." + --roles-add/skip "..." → override wins, curation flags warned and ignored (mutually exclusive per design)
Cap-aware merge with operator priority¶
When operator additions push the roster over MAX_ROLES=15, trim order is deterministic and operator-favoring:
- Plausible roles trim first (research / industry provenance)
- Observed roles trim next (posting provenance)
- Operator-added roles never trim
Trimmed entries flow to gap_flagged so the plan artifact records what got dropped.
Name + archetype dedup¶
When --roles-add "Marketing Manager" lands in a roster that already contains a Marketing Manager (or any role with archetype marketing-manager), the existing role wins - its posting/research citations are richer than the bare operator label. The add is silently skipped with a one-line log. Operators who want to force a specific variant can combine --roles-skip "Marketing Manager" with --roles-add "Demand Generation Manager" to swap.
Hard failure modes¶
- Clash between add and skip:
SkillPackConfig.validate()raisesValueErrorif the same name appears in both lists (normalized). - Curation leaves empty roster:
apply_curationraisesRuntimeErrorrather than shipping an empty pack. - Add list exceeds MAX_ROLES alone: rejected at config validation.
Artifact changes¶
role_plan.mdgains## Operator-Added Rolesand## Operator-Skipped Rolessections.role_plan.jsonRolePlanschema gainsoperator_added: list[Role]andoperator_skipped: list[str]fields.load_planhydrates them on--from-plan.- Pack report (
<Company>_Skills_Pack_Report.md) Role Composition section adds anOperator-added (via --roles-add): Nline and anOperator-skipped (via --roles-skip): N (<names>)line when applicable. - CLI completion message reports the full breakdown:
Roles: 7 (5 observed, 0 plausible, 2 added; target 5).
MCP¶
generate_skill_pack tool gains roles_add: array[string] and roles_skip: array[string] params alongside the existing roles_override / plan_only / from_plan_path / allow_recon_only. Backward compat preserved.
Tests¶
21 new curation tests in tests/skill_pack/test_curation.py covering: normalization, role materialization, cap trim order (plausible → observed → never override), the full composition matrix (add-alone / skip-alone / add+skip swap / add dedup by name / add dedup by archetype / cap overflow), and edge cases (empty roster hard error, unmatched skip warning, config-level clash detection, add-exceeds-cap rejection, dedup within roles_add and roles_skip lists). All pass; ruff clean.
[1.27.0] - 2026-05-29¶
Skill pack: holistic input layer + planning architecture rebuild¶
The skill pack subsystem treats job postings as primary input and research as supporting context. Two problems showed up against real services / reseller / consultancy companies: (1) the input layer covered only four ATS providers, missing Workday-using companies entirely; (2) the single-call discovery layer collapsed observed roles and inferred roles into one list with no provenance, making it impossible to distinguish "this role appears in actual postings" from "this role plausibly exists given the business model." Both gaps are fixed.
Input layer¶
Hiring-signal gathering (src/primr/data/hiring_signals.py) expands from 4 ATS providers to 8:
- Workday with two discovery paths: corpus-driven URL extraction (when the scrape already saw a
myworkdayjobs.comURL, hit the exact endpoint directly) and bounded blind discovery (4 datacenters × 5 site-ids per slug candidate). Posts to the public/wday/cxs/{tenant}/{site}/jobsJSON endpoint and fails closed on schema mismatch. - Workable via the public widget API at
apply.workable.com/api/v1/widget/accounts/{slug}. - Recruitee via the public offers API at
{slug}.recruitee.com/api/offers/. - Jobvite via the public RSS feed at
jobs.jobvite.com/{slug}/jobs?format=rss.
New DuckDuckGo web-search fallback (_discover_via_web_search) fires only when the ATS chain + HTML careers-page crawl both return zero postings. Filters results to known job-board hosts (LinkedIn, Indeed, Glassdoor, Workday boards, the ATS hosts) and returns metadata-only postings. The no-bodies branch was extended to populate signals.roles from posting titles when bodies aren't recoverable, so the skill pack discovery layer still sees role-type signal even when posting hosts block automated scraping.
iCIMS and BambooHR are still not covered as dedicated providers - they have no clean public JSON APIs, and the existing HTML fallback handles them.
Planning architecture¶
src/primr/skill_pack/planner.py replaces the single-call discover_roles with a two-call planning step:
- Call A - observed roles: extracts roles from hiring signals only. Every role MUST carry at least one verbatim posting citation or it's dropped. Provenance:
posting. Confidence:Confirmed. - Call B - plausible roles: infers roles from recon + research evidence + an
IndustryClassification(business model, vertical, stage, employee estimate, citations). Every plausible role MUST carry at least one specific research citation OR an explicit business-model + stage rationale. Common org-shape roles (Marketing, Sales, Customer Success, Finance, HR) become plausible only when company stage is Mid-market or larger. Generic VP and Chief-X titles are forbidden without specific evidence. Provenance:researchorindustry. Confidence:InferredorSpeculated.
Merge is archetype-based with observed-wins dedupe. The split is signal-driven - no hard ratio. Rich postings + thin research yields observed-dominant; thin postings + rich research yields plausible-dominant. Cap is roles_count; overflow goes to gap_flagged so operators can re-run with --roles-override to promote any of them.
IndustryClassification resolution is LLM-only (deterministic heuristics were considered and rejected): first parse structured fields from a primr strategic report when one is supplied via --from-report, otherwise run a single cheap LLM classification call. source field on the result records which path produced it.
Artifacts¶
The planning step writes two artifacts into the working directory before authoring begins:
role_plan.md- human-readable view with industry classification, evidence summary, observed roles + citations, plausible roles + citations, gap-flagged roles, final roster, and operator next-step hints.role_plan.json- machine view used by--from-plan. Includes the full role payload, evidence, citations, industry, and provenance per role.
The pack report (<Company>_Skills_Pack_Report.md) now shows the observed/plausible split, industry classification, per-role provenance with citation excerpts, and a reference back to role_plan.md.
Authoring¶
author_role_skills branches the authoring prompt on RoleEvidence.provenance so observed roles ground in posting evidence, research-inferred roles ground in research citations and named practices, industry-inferred roles ground in business-model typicality, and operator overrides pass through cleanly. A new provenance_guidance placeholder in author_skill.yaml injects the per-provenance steering text.
CLI¶
--plan-only- run through the planning step, persistrole_plan.md/role_plan.json, exit before authoring.--from-plan PATH- load a previously-persisted plan and author against itsfinal_rosterverbatim. Supports the plan → inspect → author workflow.--roles-override "Role A, Role B, ..."- bypass planning entirely; up toMAX_ROLESlabels.--allow-recon-only- opt in to the degraded recon-only path when both posting and research evidence are empty (the default is hard failure with a clear error message).
Configuration¶
MAX_ROLESraised from 8 to 15 for holistic packs that mix observed and plausible roles.- New
SkillPackConfigfields:allow_recon_only,roles_override,plan_only,from_plan_path. - New
RoleProvenanceenum (posting/research/industry/override) carried onRoleEvidenceend-to-end. - New
IndustryClassificationandRolePlandataclasses inschema.py;SkillPackcarries an optionalplanreference.
Hard failure on empty inputs¶
discover_roles and plan_roles now raise EmptyHiringEvidenceError when both posting evidence and research evidence are empty unless allow_recon_only=True is passed. Prevents the silent shipping of thin recon-only packs against services / reseller / consultancy companies where DNS fingerprints can't reveal the revenue-generating role layer.
Tests¶
- 13 new planner tests in
tests/skill_pack/test_planner.py(observed/plausible split, merge+cap behavior, hard-failure path, allow-recon-only proceeds, plan roundtrip persistence). - 17 new provider tests in
tests/test_data/test_hiring_signals_new_providers.py(Workday corpus discovery + bounded discovery + POST parsing, Workable, Recruitee, Jobvite, web-search filtering, title cleanup). - Existing
tests/test_data/test_hiring_signals.pyupdated to mock the web-search fallback explicitly. - Existing
tests/skill_pack/test_pipeline.pymock updated to recognize the new planning prompts. - Full suite: 7917 passed, 31 skipped, 0 failed. Ruff clean.
[1.24.4] - 2026-05-16¶
Cost estimator now reflects cross-provider routing¶
The dry-run estimator for the standard pipeline (primr "X" url --dry-run) was reporting the legacy ~$5.67/run number even when both GEMINI_API_KEY and XAI_API_KEY were configured - the v1.24.x cross-provider routing that picks gemini-3.1-flash-lite for bulk writing was implemented in pick_model_for_role but never threaded through the estimator. _estimate_fast_mode_cost was calling PrimrModels.get_grok_models(tier) directly, which always returns Grok models regardless of which keys are set.
Fixed by deferring writing-model resolution to pick_model_for_role(Role.WRITING) for the FAST and HYBRID tiers. --grok-tier max still uses Grok-everywhere - that flag is the explicit user opt-in to the all-Grok stack. The estimate now reports:
- Standard run, no AI strategy: ~$0.76 (matches the README's $0.79 claim and the v1.24.0 stage-1 eval)
- Standard + verify: ~$0.78
- Standard + 1-vendor AI strategy: ~$0.89
- Standard + 2-vendor AI strategy (typical default): ~$1.01
--grok-tier max: ~$3.38 (Grok-everywhere, as before)
The displayed mode notes now also show the actual resolved model pair (grok-4.3 reasoning + gemini-3.1-flash-lite writing) rather than the hardcoded 4.20-nr writing string.
Docs¶
- Updated stale
routing.py:pick_model_for_roledocstring that still described v1.23.0 single-provider behavior. The actual code has run the v1.24.x cross-provider chain since v1.24.0.
Tests¶
- Three test cases that assumed Grok-only writing (
test_max_tier_cheaper_writing_than_hybrid,test_fast_tier_cost_range,test_hybrid_tier_cost_range) were rewritten to monkeypatch env vars to a deterministic state and to assert the correct relationship for both XAI-only and Gemini+XAI configurations. - Added
test_hybrid_cheaper_than_max_with_geminiandtest_hybrid_tier_cost_range_with_geminias forward-looking regression guards for the v1.24.x routing.
[1.24.3] - 2026-05-16¶
Re-release of v1.24.2: prior release had primr.__version__ still at 1.24.1 while pyproject.toml was at 1.24.2, breaking the package-version integrity check. v1.24.2 was yanked from PyPI; v1.24.3 is the clean release.
Artifact drift cleanup (roadmap item #1)¶
Internal scaffolding markers were leaking into shipped reports more often than the roadmap previously estimated. A scan of 16 recent reports found 240 [workbook] markers, 87 [cross-ref ...] markers, and 65 bold-wrapped **What to validate:** lines that should never reach a deliverable. Three root causes, all fixed:
[cross-ref ...]cleanup was too narrow. The strip regex in_clean_fast_report_outputrequired a colon (\[cross-ref:), so the space-separated variant the model actually emits most often ([cross-ref Financial Profile]) sailed through. Broadened to match colon-separated, space-separated, and bare forms. Verified on five historical reports: 28 leaked instances stripped to 0.[workbook]cleanup missed the bare and space-separated forms. The existing regexes caught[Workbook: ...],[workbook section ...], and[Workbook §...]but missed bare[workbook]and[workbook ARDA/prior sections]- the variants the model emits when treating workbook as a literal source citation. Replaced with one inclusive[workbook(?:[\s:§]...)?\]regex. Verified: 51 leaked instances stripped to 0.- Bold-wrapped
**What to validate:**lines bypassed normalization._normalize_generated_section_payloadmatched^What to validate:but not**What to validate:**, so bolded variants leaked into the body alongside a separately-appended default trailing line. New regex recognizes optional leading/trailing bold or italic emphasis and dedups into the single canonical trailing line.
ReportAnalyzer scaffolding-leakage check¶
Added analyze_scaffolding_leakage() to ReportAnalyzer covering the four leak categories above plus informal [cite: workbook] / [cite: bbb] cite labels that should never ship. Surfaced as a warning block in generate_report() when total_leaked > 0; clean reports stay terse.
Bonus fixes¶
analyze_urls_and_sources()had a hardcoded vendor domain as the "company_website" category - a leftover from one early test report that was meaningless for every other run. Replaced with a genericprimary_hostderived from the most-cited non-news, non-LinkedIn domain.- Fixed a
lstrip("www.")bug in the same area (would have stripped any leadingwor.character, not the literal prefix) - switched toremoveprefix("www.").
Tests¶
- +5 normalization tests in
tests/test_core/test_fast_mode_research.pycovering bold-wrapped validate lines (with content, fully bolded, bare), space-separated cross-ref, and bare workbook variants. - +6 ReportAnalyzer tests in
tests/test_qa/test_report_analyzer_deterministic.pycovering each leak category and the combined total.
[1.24.1] - 2026-05-13¶
Re-release of v1.24.0 with sanitized docs (generic placeholder for eval-target company). No code changes.
[1.24.0] - 2026-05-13¶
Sub-$1 default via cross-provider eval¶
Cross-provider eval picked Grok 4.3 reasoning + Gemini 3.1 Flash-Lite writing as the new default - verified at $0.79/run (vs $3.49 on the previous Grok-only hybrid, 4.4x cheaper with trust gate PASS and faster runtime). Default auto-selects when both XAI_API_KEY and GEMINI_API_KEY are configured; XAI-only setups stay on the legacy ~$4.27/run path.
Provider-aware role routing¶
pick_model_for_roleuses a provider-aware fallback chain: WRITING/UTILITY prefer GEMINI > OPENAI > ANTHROPIC > XAI; REASONING prefers XAI (Grok 4.3 cached) > GEMINI > OPENAI > ANTHROPIC.- OpenAI-only users get gpt-5.4-nano writing + o4-mini reasoning; Anthropic-only users get Haiku + Sonnet.
grok_llmextended with cross-provider dispatch so writing-tier calls reach the right provider when the resolved model is non-Grok.- OpenAI provider switched to
max_completion_tokensfor the gpt-5.x family. - PRO role split into REASONING + WRITING + UTILITY in
routing.py;EvalRecipeOverridecontextvar added for per-run recipe forcing.
Eval profile slot registry¶
src/primr/core/model_eval.py + src/primr/config/eval_profiles.py gain a profile slot registry with 11 candidate slots - one slot per (provider × model × role-recipe). New models register a slot, run the corpus once, and score against existing baselines without re-doing prior work.
Pipeline resilience¶
Phase 5 enrichment loop got a 5-minute per-section deadline (had been unbounded). Stops runaway regeneration loops without affecting the common case.
Full decision audit in docs/EVAL_V1_24_0.md.
[1.23.0] - 2026-05-08¶
Multi-provider foundation¶
- OpenAI integration via
OpenAICompatibleProvider.gpt-5.5,gpt-5.4,gpt-5.4-mini,gpt-5.4-nanoregistered with cached-input pricing.OPENAI_API_KEYauto-detected.reasoning_effortplumbed through provider kwargs. - Ollama / local-inference via
OpenAICompatibleProvider.qwen3-coder:30b,qwen2.5:32b,deepseek-r1:32b,qwen3:7bregistered at zero marginal cost.OLLAMA_BASE_URLenv honoured;api_key_default="ollama"so the OpenAI SDK accepts the call. - Anthropic Claude provider as a separate class (
src/primr/ai/providers/anthropic.py). System-message translation, retry/backoff, billing-exhaustion detection raisingQuotaExhaustedError, cache-aware token tracking.claude-opus-4-7,claude-sonnet-4-6,claude-haiku-4-5registered. - Quota-aware fallback infrastructure in
ModelCircuitBreaker.execute_with_fallback()- consumesQuotaExhaustedError, marks the provider exhausted with midnight-UTC reset, advances through cross-provider chains. Per-call-site integration into the production pipeline is scoped to v1.24.0. - Prompt-cache token plumbing. Providers extract cached counts from xAI / OpenAI (
prompt_tokens_details.cached_tokens/cached_tokens) and Anthropic (cache_read_input_tokens/cache_creation_input_tokens)._UsageAccumulatoraggregates them;get_usage()exposes them. Bridging into per-runUsageRecordandprimr show-usageis scoped to v1.24.0.
Skills Ideation strategy (--strategy-type skills)¶
- New YAML-defined strategy at
src/primr/prompts/strategies/skills.yamlthat ideates a top-5 roles x top-3 skills hypothesis grounded in DNS recon and hiring signals. - Per-role
SKILL.mdemission viasrc/primr/output/skills_generator.py. Selecting--strategy-type skillsproduces both the strategy markdown/DOCX andoutput/<Company>_Skills_Ideation_<date>/roles/<slug>/SKILL.mdfiles with propername/descriptionfrontmatter - drop-in for Claude Code, Copilot Studio, or any skill-aware agent host. - YAML strategy context loader extended to also pull
_recon_context.txtand_hiring/hiring_signals.md. This change strengthens the existing Customer Experience, Modern Security, and Data Fabric strategies as a side effect - they now see recon and hiring signals which previously only reached the AI strategy path. - Sparse-signal companies pivot to industry-baseline mode and say so explicitly rather than fabricating roles, per the YAML's mandatory Signal Strength section.
Anthropic correctness fixes¶
- Opus 4.7 context window corrected to 1M (was 200K), output corrected to 128K (was 32K).
- Sonnet 4.6 context window corrected to 1M (was 200K).
- Haiku 4.5 output corrected to 64K (was 16K),
supports_thinking=True. - Removed bogus
cache_control_blocksprovider-kwarg passthrough - Anthropic prompt caching is configured at the message-content level (cache_control directives inside content blocks), not as a top-level API parameter. The previous plumbing would have raisedTypeErrorif a caller actually used it. - Opus 4.7 tokenizer-inflation caveat (~35% more tokens than 4.6 for the same input) documented in
ModelRegistry.
Misc fixes¶
--helpno longer crashes Python 3.10 on Windows when stdout decodes as UTF-8 - replaced the lone×(multiplication sign) in the skills strategy description withx.UTILITY_FALLBACK_CHAINnow referencesPrimrModels.GROK_MODEL_WRITINGinstead of the hardcoded"grok-4.20-non-reasoning"string.- mypy fix in
core/cli.pyxAI key-verification branch.
[1.22.0] - 2026-05-03¶
Grok 4.3 onboarded as flagship reasoning model¶
grok-4.3registered inModelRegistry($1.25/$2.50 per 1M with $0.20 cached input, 1M context, configurable reasoning effort). HYBRID and MAX tiers now route reasoning stages to 4.3; FAST stays on 4.1; legacygrok-4.20-*IDs remain registered for resume of in-flight runs.ModelConfigextended withcost_per_1m_input_tokens_cached.calculate_costnow acceptscached_input_tokensand bills the cached portion at the discount rate when the model exposes one.- Analysis fallback chain reordered to
(4.3 → 4.20 → 4.1 → Flash). docs/MODEL_ONBOARDING.mdadded - five-step playbook (verify → register → wire → test → eval-gate) for future model additions, with Grok 4.3 as the worked example. Referenced fromREADME.md.
Utility-tier LLM calls migrated to Grok when XAI_API_KEY is set¶
llm()now routes scraping summaries / link selection / generic "fast" calls to Grok 4.1-NR whenXAI_API_KEYis set. Grok 4.1-NR is 2.5x cheaper input and 6x cheaper output than Gemini Flash and lives on the same key the standard pipeline already uses.- The standard pipeline no longer requires a Gemini key -
XAI_API_KEYalone is sufficient.GEMINI_API_KEYis now only needed for--premiummode (or as a utility-tier fallback when no xAI key is set). - Surfaced when a stalled Gemini Flash link-selection call hung the first 4.3 comparison run; the cross-provider dependency was a historical artifact, not a deliberate design.
Provider abstraction and routing layer¶
src/primr/ai/providers/new package:ProviderABC,ChatResponse,ProviderUnavailableError,QuotaExhaustedError, shared_UsageAccumulator, plus three concrete provider classes:OpenAICompatibleProvider- single class for any OpenAI-shaped endpoint, parameterized bybase_urlandapi_key_env. xAI / OpenAI / Ollama / vLLM / llama.cpp all become one-line registry entries.GeminiProvider- wrapsgoogle.genai, translates message lists intosystem_instruction+contents, raisesQuotaExhaustedErroron daily limits.ProviderRegistry(registry.py) - auto-detects which providers are configured from env keys.src/primr/ai/routing.py- single source of truth for "which model for which role".pick_model_for_role(role)andget_provider_for_model(name)replace the previous scatteredif XAI_API_KEYchecks.grok_llm,ContinuousReasoningSession, andllm()delegate to providers internally; public signatures unchanged.primr doctorgains a "Providers" section listing each configured provider and the roles it serves.- 60+ new tests across
test_providers.py,test_provider_registry.py,test_routing.py,test_grok_client.py,test_llm_dispatch.py. Full suite remains green: 4945 pass, 28 skipped (optional deps). docs/MODEL_ONBOARDING.mdgains an "Adding a new provider" section covering OpenAI-compatible vs distinct-SDK cases.
Eval-gating of the 4.3 default flip¶
The default flip from 4.20-hybrid to 4.3-hybrid was made on mechanical wiring + vendor recommendation. The full 4-way scorecard sweep (fast / hybrid / max / premium against the 4.20-hybrid baseline) is queued as the first item in the v1.23.0 roadmap.
[1.21.2] - 2026-04-30¶
Output Directory and Recon Platform Defaults¶
--output-dirnow applies to the research pipeline. The CLI parser already accepted the flag, but the main research handler did not pass it through. Reports and strategy documents now write to the requested directory across standard, fast, deep, and strategy-only paths.- Custom output folders are client-clean. When
--output-diris set, Markdown and DOCX deliverables are written there; TXT mirrors and artifact validation diagnostics are kept under the run diagnostics folder instead of cluttering the client folder. - Recon platform selection now uses strong infrastructure signals only. DNS productivity, email, and certificate signals such as Microsoft 365, Google Workspace, Google Trust, AWS SES, and AWS ACM remain available as recon context but no longer declare a primary AI strategy cloud.
- Fallback strategy posture is Microsoft + private cloud/NVIDIA. If recon is unclear or skipped, Primr defaults to
azure privateinstead of a generic agnostic or accidental all-cloud posture.
[1.21.1] - 2026-04-29¶
Skill async-monitoring guidance: behavioral, not tool-specific¶
claude-code/skills/primr/SKILL.md"Async monitoring" rewritten as a four-tier preference list, ordered from cleanest to fallback: (1) background launch with completion notification if the host supports it, (2) phase-marker streaming from the log if the host can tail-and-emit, (3) a one-shot sanity check at +5min to catch first-phase failures, (4) honest "I'll check back in about an hour" when no async primitives are available. Same change inAGENTS.md(regenerated from the skill body). The earlier copy implied the agent should statelessly wait for the user to ping - the new copy lets the agent pick the lightest mechanism its host actually supports.- No prescribed tool names. The skill describes what the agent should want (one event on completion, light progress signals, early-fail catch) without assuming a specific Claude Code tool exists. Hosts with stronger async primitives (Claude Code's
run_in_background,Monitor) get the cleaner experience; portable hosts get the honest "back in an hour" path. - Explicit "what not to do" section: no sub-minute polling, no promised heartbeat cadence the host can't deliver, no treating "still running at 60 minutes" as failure.
[1.21.0] - 2026-04-29¶
Native AI-tool integration: Claude Code plugin, AGENTS.md, per-host clients¶
primr now ships full agent-host integration mirroring the recon layout. After pip install primr, AI-tool integration is one paste away - no install subcommand, no JSON-merge tooling, no host-specific glue inside the CLI.
claude-code/plugin directory -.claude-plugin/plugin.json,.mcp.json(registersprimr mcpover stdio), andskills/primr/SKILL.mdwith threereferences/files. Installable via/plugin marketplace add blisspixel/primrthen/plugin install primr@blisspixel-primronce a marketplace catalog is registered.clients/directory - copy-pasteable MCP snippets for Kiro (clients/kiro/mcp.json), Windsurf (clients/windsurf/mcp_config.json), Cursor, VS Code + Copilot, and Claude Desktop. Each entry uses the unified{"command": "primr", "args": ["mcp"]}shape. README documents per-host file paths plus the macOS GUI-PATH gotcha.AGENTS.mdat repo root - same body asSKILL.mdminus the frontmatter, in the agents.md standard format. Auto-detected by Kiro, Codex, Aider, Jules, and any other tool that loadsAGENTS.mdwithout configuration.primr mcpsubcommand - single-binary entry point matching the reconrecon mcppattern.primr mcpdefaults to--stdio(the canonical Claude Code use case);primr mcp --http --port 8000still works. The legacyprimr-mcpconsole script is preserved for backwards compatibility.- SKILL.md is agentskills.io-compliant - same file works in Claude Code skills, Kiro skills, and any other host that follows the open Agent Skills standard. Encodes the cost gate, async-on-next-turn lifecycle, mode/tier/platform selection heuristics, hypothesis memory pattern, and behavioral deferral rules ("vague research → use the host's web search; DNS-only → shell out to dig").
- README "Use primr from your AI tool" section - leads with the one-line "tell Claude to fetch this URL and save the skill" install for users who don't want the full plugin, plus the plugin install commands for users who do.
Why this shape¶
We considered (and ruled out) shipping primr install-skill and primr install-mcp subcommands. The recon project's pattern proved better: skills live at stable raw GitHub URLs, the AI is the installer ("fetch this URL"), and per-host config snippets are copy/paste rather than auto-merged into user-owned files like ~/.claude.json. Less primr code, no risk of corrupting user config, and the same SKILL.md works across Claude Code, Kiro, and any other agentskills.io-compliant host.
[1.20.4] - 2026-04-29¶
Critical: PyPI Wheels 1.20.1 - 1.20.3 Were Missing Data Files¶
PyPI installs of primr 1.20.1 through 1.20.3 crashed on the first research run with FileNotFoundError: ... primr/config/prompts.json. Source checkouts were unaffected. The wheel was packaging only py.typed because [tool.setuptools.package-data] in pyproject.toml did not include the JSON or YAML files that live inside the primr package.
- Fix in
pyproject.toml-[tool.setuptools.package-data]now shipsconfig/*.json,prompts/*.yaml,prompts/shared/*.yaml, andprompts/strategies/*.yamlalongsidepy.typed. Localpython -m buildconfirms 14 data files pluspy.typedare present in the resulting wheel (vs. 1 file in the broken builds). - Anyone on 1.20.1 - 1.20.3 from PyPI must upgrade:
pip install -U primr.
--version Flag¶
primr --versionnow printsprimr <semver>, sourced fromprimr.__version__. Previously argparse rejected the flag with "unrecognized arguments: --version".
[1.20.3] - 2026-04-29¶
Live Key Validation in primr init¶
- Pasted keys are now verified before they are saved.
_validate_key_live(provider, value)insrc/primr/core/cli.pymakes a cheapmodels.list()call against Gemini (google-genai) or xAI (openaiSDK pointed athttps://api.x.ai/v1). On 401/403/"invalid key" responses, the user sees a clear "rejected by provider" message and is offered up to two retries. Network/transient failures fall back to "could not verify" and let the user retry or skip without a hard block. - Replace path for already-configured keys. Previously, init silently skipped any key whose value looked configured (length ≥ 10), which left no obvious way to recover from a bad paste. Init now shows the masked existing key and asks "Replace? (only if the saved key is wrong) [y/N]" - defaulting to no, so the common path stays one keystroke. Saying yes drops into the same paste-and-validate flow used for first-time setup.
- No-token validation.
models.list()is metadata-only, so verification has zero token cost. Tests covering init/keys flows still pass (99/99).
[1.20.2] - 2026-04-29¶
Friendlier Missing-Key UX¶
- No more "open the .env file" prompt for missing keys. When
primr "Company" urlis run without API keys configured, primr now offers to set them up inline: each key prompt explains why it's needed (with cost estimates) and where to get one (with a hint about free tiers/credits), and the user pastes the key directly into a hidden prompt. Pasted keys are saved to the per-user config file - no manual.envediting. - Auto-launches when validation fails.
src/primr/core/cli.pynow detects validation failures whose only errors are missing API keys, and offers the guided init flow inline if stdin/stdout is a TTY. After keys are saved, the original command continues automatically - users do not have to re-run their command. - Updated suggestion copy in
src/primr/utils/config_validation.pyso the missing-key error leads withprimr initrather than a "set this in .env" instruction.
[1.20.1] - 2026-04-26¶
PyPI Release Infrastructure¶
.github/workflows/release.yml- release workflow that triggers on tag push (v*) and supports manual dispatch from the Actions tab. Two-stage pipeline:buildverifies the tag version matchespyproject.toml, builds sdist + wheel viapython -m build, runstwine checkon the distribution metadata, and uploads artifacts;publishtargets thepypienvironment so deploys can be gated on review and uses the PyPI trusted-publisher OIDC flow (no API token in repo secrets).- PyPI listing metadata already in place:
pyproject.tomlcarries the project URLs (Homepage, Documentation, Repository, Bug Tracker), classifiers (Development Status, Intended Audience, Python versions, Topics), keywords, and MIT license. First PyPI publish picks all of this up automatically.
Repo Cleanup¶
- Root
.mdreduced toREADME.mdandROADMAP.md.CHANGELOG.md,CONCURRENCY.md,CONTRIBUTING.md, andSECURITY.mdmoved intodocs/. All internal links updated (README,docs/INDEX.md,docs/CHANGELOG.mdself-link,MANIFEST.in).ROADMAP.mdstays at root because the agenticRoadmapAPI, MCPagentic_resources/agentic_toolsmodules, and the roadmap property tests all hardcodePath("ROADMAP.md"). CLAUDE.mdremoved from version control (added to.gitignore, untracked viagit rm --cached). It is project-level instructions for the local Claude Code workflow - useful locally, noise for anyone reading the public repo who does not use Claude Code. The local file on disk is untouched.- ROADMAP entry queued: when shipping to PyPI, fold
setup_env.py's post-install steps (.envtemplate creation, Playwright/Patchright browser install, Python version validation, doctor handoff) into aprimr initsubcommand so PyPI installs get the same convenience as source installs without a separate top-level script.
[1.20.0] - 2026-04-26¶
Continuous Reasoning Session - Now Default¶
After an n=3 paired-comparison pilot (rich/mid/sparse signal density, blind LLM judge), the continuous-reasoning topology is now the default for the standard Grok 4.20 pipeline. Workbook generation (Phase 3) and cross-validation (Phase 5) share a single Grok session so the validator inherits the corpus + workbook reasoning instead of re-reading the report cold.
- New class
ContinuousReasoningSessioninsrc/primr/ai/grok_client.py: multi-turn Grok session that preserves message history across stages, with the same retry/error/token-tracking semantics as the existinggrok_llmhelper. One session per primr run. - Wired into the standard Grok pipeline: workbook generation and cross-validation share the session. Section writing (Phase 4) is intentionally unchanged - it stays parallel + fresh-call per section since the topology change is targeted at sequential reasoning handoffs, not parallel sub-agents.
--continuous-reasoningis on by default. Pass--no-continuous-reasoningto revert to the fresh-call topology for a single run, or setPRIMR_CONTINUOUS_REASONING=0(orfalse/no/off) to disable across all runs on the machine.- Lazy session construction with proper
role:system: the session is constructed at the workbook stage so the workbook's system prompt becomes a realrole:systemmessage at session init. (An earlier implementation that folded the system prompt into the first user turn measurably degraded workbook quality during the pilot; the fix is in.) - Pilot results that drove the default-change decision: workbook quality improved 3/3 by blind judge, cross-validation quality improved 2/3 (one close call), final report quality improved 2/3 with one judge call complicated by a separate baseline-pipeline drift issue (now its own ROADMAP entry - "Artifact Drift in the Standard Pipeline"). Quantified drift reduction independent of judge opinion: bare leaked-instruction lines drop from an average of 5.3 per baseline report to 1.0 per continuous report (~81% fewer). Cost delta ranged −3.7% to +32% across runs (average ~+12%); never catastrophic, well under the 40% pre-flip gate.
[1.19.0] - 2026-04-21¶
Hiring-Signal Gathering - Job Posts as Strategic Input¶
- New module
src/primr/data/hiring_signals.py: after the main-site scrape, Primr discovers a company's open job postings and extracts strategic signals - tech-stack frequency, initiatives, culture cues, notable absences. Job posts are one of the most honest signals a company emits about what they're actually building right now. - ATS board APIs first: Greenhouse (
boards-api.greenhouse.io), Lever (api.lever.co), Ashby (api.ashbyhq.com), and SmartRecruiters (api.smartrecruiters.com) public job-board endpoints are probed in parallel against slug candidates derived from the company name, website hostname, and any recon-supplied ATS hints. First provider returning a non-empty board wins. - HTML careers-page fallback: when no ATS matches, Primr crawls the company's own careers page via the popup-free external orchestrator, extracts individual posting URLs with a regex scan, and fetches up to 15 bodies.
- LLM triage: a small Grok call picks up to 15 postings biased toward senior, engineering, product, data, security, and platform roles; retail, sales SDR, and entry-level roles are down-weighted. Deterministic title-based ranker as fallback when the LLM call fails.
- Batched LLM extraction: one Grok reasoning call over the aggregated JD text produces structured JSON - roles & locations, tech-stack frequency map, strategic initiatives, culture signals, locations, hiring volume, notable absences, and a one-paragraph summary. Robust JSON parser handles fenced blocks and prose-embedded JSON.
- Downstream integration: extracted signals are threaded into
insights.txtand the raw external-sources bundle so every downstream phase - gap analysis, workbook, section writing, cross-validation, and Phase 6 strategy - sees them. The rebuild that happens during Phase 2 gap-filling preserves the hiring block. - Artifacts persisted to
<working>/_hiring/: human-readablehiring_signals.md, structuredhiring_signals.json, fullpostings_index.json, and raw JDs underraw/jd_NNN_<slug>.txtfor auditability. - Fail-open at every stage: no ATS match and no careers page → the phase records
source: noneand continues. LLM triage or extraction failure → skeleton artifact with counts but empty signals. Companies that don't publish jobs produce reports unchanged. - Cost/time: ~$0.01 and +1-2 min baked into
--dry-run. Disable entirely withPRIMR_SKIP_HIRING_SIGNALS=1. - 40 new unit tests at
tests/test_data/test_hiring_signals.py: slug guessing, HTML stripping, JSON parse robustness, every ATS provider parser (including malformed-response handling), HTML fallback link extraction, triage fallback, extraction coercion, render_for_prompt, end-to-end with fully-mocked HTTP + LLM, env-toggle skip, recon-hint priority, and posting staleness.
Scraping Resilience - Routing Around Bot Protection¶
- Recon moved to external
recon-toolpackage: the embeddedsrc/primr/recon/module was deleted; primr now depends on the standalonerecon-tool(PyPI) so recon work can evolve in its own repo.primr recon <domain>CLI shorthand still works via mount ofrecon_tool.cli:app.dnspythonremoved as a primr dependency (owned by recon-tool now). - Patchright stealth-browser tier (
src/primr/data/scraping/stealth_browser.py): real-Chrome + persistent per-host user-data-dir, bypasses Kasada / Akamai / PerimeterX challenges that blank plain Playwright. Two-phase: headless first, headed only if headless returns a challenge shell. - First-time browser install is automatic: on first scrape that needs Patchright, primr runs
python -m patchright install chromiumin a subprocess with a one-line CLI notice. No manual setup required - baked into install. - Global headed-popup budget (default
0, opt in per run withPRIMR_MAX_HEADED_POPUPS=N): single shared counter across the Patchright stealth tier and the orchestrator's adaptive Playwright retry. At the default of 0 no visible-browser windows ever open; blocked pages go straight to public-data fallbacks. SetNto allow up to N total popups for a run. On Linux the budget is automatically treated as 0 unlessDISPLAYorWAYLAND_DISPLAYis set, so headless servers skip the visible-browser path entirely. - Shared popup budget covers adaptive retry (
src/primr/data/scraping/headed_budget.py): the orchestrator's per-host adaptive browser retry (Playwright / Playwright Aggressive) now consumes the same counter as the Patchright stealth tier, so validation passes can't independently pop a new window per soft-blocked URL. - No more host-pinning to headed mode:
HostState.browser_headed_preferredsticky flag removed - a successful headed retry no longer locks the host into headed mode for subsequent pages. The host falls through to fallback tiers on later requests. - Tiny, minimized, off-screen popup: when Patchright does go headed, the Chrome window is resized to 320x200 via CDP, minimized to the taskbar, and positioned off-screen before navigation starts. Chrome profile
Preferencesis also sanitized to prevent saved maximized state from overriding. - Low-value URL filter: Glassdoor, Indeed, G2, Capterra, LinkedIn, Twitter/X, Reddit, privacy/terms/cookie paths etc. skip Patchright entirely. No popup possible on those.
- External-source orchestrator (
get_external_orchestrator): web-search validation and discovery scrapes use a popup-free orchestrator (Patchright stripped from tier list). Blocked external sources are silently skipped. - Per-host rate-limit memory (
src/primr/data/scraping/rate_limit_state.py): 429 responses record a 20-minute cooldown (expandable on repeat) atlogs/rate_limit_state.json. Subsequent scrapes on cooldown hosts skip live fetch and go straight to public-data fallbacks with a clear user-facing message. - Public-data fallback fan-out (
src/primr/data/fallback_sources.py): when the origin is blocked or returns zero pages, primr fetches content in parallel from Wayback Machine (CDX API), live sister subdomains (investor./ir./newsroom./press.), SEC EDGAR 10-K filings, Wikipedia REST API, and xAI Grok surrogate synthesis. Fails open - any one source returning content produces a report. - Grok surrogate (
grok_browse_and_summarizeinprimr.ai.grok_client): uses xAI's Responses API withweb_searchagent tool to fetch URLs or synthesize equivalent content from public sources when direct fetch fails. Returns citations. Opt-out viaPRIMR_DISABLE_GROK_SURROGATE=1. - "Thin website data" threshold widened: 3 rich fallback pages totalling 60K+ chars no longer trigger the "thin" branch - char volume is the real signal, not page count.
- Wayback parallelized and bounded: CDX lookups run concurrently across candidate URLs with a hard 75s total deadline; can't starve the fan-out budget.
- New tests:
tests/test_data/test_fallback_sources.py(12),tests/test_data/test_scraping/test_rate_limit_state.py(9). Existingtests/test_data/test_external_sources.pypatch paths updated for new orchestrator routing.
[1.18.0] - 2026-04-10¶
Recon Integration - DNS Intelligence Pre-Flight¶
- Recon as first-class module: DNS intelligence tool relocated from standalone
recon/intosrc/primr/recon/, fully integrated into primr's package, linting, type checking, and CI primr reconsubcommand: Standalone DNS intelligence lookups -primr recon acme.comreturns company name, email provider, tenant ID, 156 SaaS service fingerprints, email security score, and 20 signal intelligence rules. Supports--json,--md,--services,--full, batch mode, andprimr recon doctor- Auto-platform detection: Recon runs automatically before scraping, detects cloud platform(s) from DNS fingerprints (AWS Route 53, Azure DNS, GCP DNS, etc.), and auto-selects
--platformvalue. Override with explicit--platformflag - Recon context injection: Detected services, signal intelligence, email security, auth type, and infrastructure insights injected as context into all strategy types (AI, Security, CX, Data Fabric)
--cloud-vendorrenamed to--platform: Cleaner flag name.--cloud-vendorkept as deprecated alias with warning--platform msshorthand: Expands toazure privatefor the common Microsoft + NVIDIA combo--skip-reconflag: Opt out of DNS pre-flight stepCloudVendor→Platformenum rename:CloudVendorkept as deprecated alias for backward compatibility- Pipeline integration: Recon results logged, recorded in
_run_state.json, included in--dry-runcost estimates ($0.00, ~2-3 seconds) - Property-based tests: 4 correctness properties validated with Hypothesis (platform mapper purity/ordering, formatter section presence/determinism)
- 156 fingerprints: 13 new detections including Box, Egnyte, Glean (Enterprise AI Search), Datadog, New Relic, PagerDuty, Render, Ping Identity, CyberArk, Lakera (LLM Guardrails), Cato Networks (SASE), Rippling, Deel
- 20 signal rules: 7 new signals including Zero Trust Posture, AI Security Posture, Shadow IT Risk, Startup Tool Mix, Dual Email Provider, Observability & SRE, File Collaboration Sprawl
- Certificate transparency: Passive subdomain discovery via crt.sh integration
- SRV record detection: Skype for Business, XMPP, CalDAV, CardDAV
- Expanded DKIM: ESP selectors for Mailchimp, SendGrid, Mailgun, Postmark, Mimecast
- Custom signals: User-defined signals via
~/.recon/signals.yaml(additive, mirrors fingerprint extensibility)
[1.16.0] - 2026-03-23¶
This release consolidates all work from v1.7.0 through v1.16.0. See ROADMAP.md for the detailed changelog.
Added¶
- A2A Protocol Integration - Agent-to-agent communication with AgentCard, executor, client, hooks, and 165 dedicated tests
- Standalone
primr-a2aserver or co-hostedprimr-mcp --http --a2a delegate_to_agentMCP tool for calling external A2A agents- Governance hooks: SSRF, cost budget, content sanitization
- Grok 4.20 Hybrid Tier - 4.20 reasoning + 4.1 writing as new default,
--grok-tierflag (fast/hybrid/max), per-model cost tracking, calibrated estimates - Private Cloud Vendor - NVIDIA-first, on-prem AI strategy via
--cloud-vendor private - Agentic Architecture (v1.7.0) - Hypothesis tracking, subagents (scraper, analyst, writer, QA), hook system (cost guard, SSRF guard, QA gate), orchestrator, research memory, Claude Skills
- Output Improve Mode -
primr improve <path>for deterministic cleanup + optional--improve-agenticreview pass - Versioned Eval Workflow -
primr --evalwith scorecards, auto-staging, LLM-judge overlays (cloud and local), multi-model sweeps - Fast Mode as Default - Auto-detects Grok 4.1 when
XAI_API_KEYset;--premiumfor Gemini + Deep Research - Startup Banner - Animated ANSI gradient with 5-layer terminal fallback, cross-platform
- Adaptive Output Shipping Gate - Deterministic salvage pass, DOCX pre/post validation, strategy-only reruns
- Agentic Pipeline - Adaptive search depth, source quality filtering, dynamic section selection, 2 new report sections (23 total)
- Deep Research Refactor - Shared parsing/polling/execution modules, durable async recovery,
--resume-latest,--resume-local - Shared AI Error Policy - Unified sync/async retry classification
- Scraping Reliability - Adaptive lazy-load scrolling, strict quality gate, scrape trace logging, external search caps
- Content Sanitization (v1.8.1) - Prompt injection protection
- Interactive Research Mode (v1.11.0) - Expanded external search, MCP progress subscriptions
- Multi-Cloud-Vendor AI Strategy (v1.12.0) -
--cloud-vendor aws azurefor multi-vendor strategy documents - Strategy Enrichment - Cross-validation, evidence search, section regeneration, polish pass, pre-ship repair
- Gemini 3.1 Pro Preview - Registered with tiered pricing in ModelRegistry
- All Strategy Types in Fast Mode -
--strategy-typeworks with Grok pipeline, YAML configs auto-discovered
Fixed¶
- Silent Failure Audit - 45+ bare
except: passand DEBUG-level error handlers upgraded across 23 modules - Report Quality - Duplicate section elimination, coherence pass rewrite (guard threshold 0.92→0.96), contradiction resolution
- Scraping Robustness (v1.12.1) - PDF routing, bug fixes
- SharedBrowser (v1.11.2) - ETA progress, UI polish
- Deep Research Progress (v1.11.1) - Visibility and failure recovery
Changed¶
- Default pipeline uses Grok 4.20 hybrid (was Grok 4.1)
- Strategy
max_tokensraised from 16K to 32K - Executive summary written last (with full report context)
- Parallel external source search (
ThreadPoolExecutor(max_workers=3)) - Framework section word targets raised from 600 to 800
[1.6.0] - 2026-02-03¶
Added¶
- Serverless Cloud Deployment - Full job-based ephemeral execution for AWS, Azure, and GCP
- Job runner contract with manifest-as-commit pattern
- Artifact storage abstraction (S3, Blob Storage, GCS)
- Control plane API (submit, status, cancel, results)
- Event-driven queue boundary (SQS FIFO, Service Bus, Pub/Sub)
- State reconciliation for stuck/orphaned jobs
- Comprehensive SSRF protection (RFC1918, metadata IPs, DNS rebinding)
- Per-API-key rate limiting and quota enforcement
- OpenTelemetry tracing with job_id correlation
-
Structured JSON logging with sensitive data redaction
-
AWS (Primary - Production Ready)
- Lambda control plane + Fargate job runner
- ECR lifecycle policy (keep last 10 images)
- S3 lifecycle rules (IA transition after 30 days, version cleanup)
- SQS dead-letter queue for failed messages
- Step Functions with least-privilege IAM roles
- X-Ray tracing on reconciler Lambda
-
CloudWatch alarms (Lambda errors, DynamoDB throttling, DLQ, queue age)
-
Azure (Reference Implementation)
- Container Apps control plane + Container Apps Jobs runner
- Cosmos DB autoscale (400-4000 RU/s)
- Managed identity with RBAC roles
-
Application Insights for monitoring and tracing
-
GCP (Reference Implementation)
- Cloud Run control plane + Cloud Run Jobs runner
- Dedicated service account (not default App Engine SA)
- Least-privilege IAM roles
- Firestore composite indexes for efficient reconciler queries
- Cloud Scheduler with dedicated service account for OIDC auth
Documentation¶
- docs/CLOUD_DEPLOYMENT.md - Serverless deployment guide
- Updated README.md with cloud deployment section
- Updated ROADMAP.md with v1.6.0 completion
[1.5.1] - 2026-02-02¶
Added¶
- JWT signature verification (HMAC-SHA256/384/512)
- Security headers middleware
- Request ID tracking
- Rate limit headers
- API key rotation with grace periods
- API key expiration support
- Security utilities module
- Security operations guide
Fixed¶
- Removed dead code in deep_research.py
- Fixed Python 3.10 compatibility in MCP server modules
- Added missing COMMON_PAGE_PATTERNS re-export in scrape.py
- Fixed exception chaining in multiple modules
- Fixed ambiguous variable names
- Fixed multiple statements on one line in browsers.py
- Removed duplicate method definitions in qa/integration.py
- Fixed import shadowed by loop variable in type_guards.py
Changed¶
- CORS now restricts origins, methods, and headers
- JWT tokens require valid signatures
- Admin tokens hashed before comparison
Documentation¶
- docs/SECURITY_REVIEW_2026-02-02.md
- docs/SECURITY_OPS.md
[1.5.0] - 2026-02-02¶
Added¶
- Typed error hierarchy with automatic retry classification
- Circuit breaker with per-host failure tracking and monitoring
- OpenTelemetry integration for distributed tracing
- Configuration validation with early startup checks
- State machine specifications for tier escalation and job lifecycle
- Unified async/sync boundary handling via
async_utilsmodule - 282 property-based tests using Hypothesis
Changed¶
- Migrated all error classes to typed error hierarchy
- Legacy error names (AIError, ScrapingError, etc.) now alias to typed classes
- All errors now have
user_message(),debug_message(), andguidanceattributes - Error formatting utilities updated to use typed hierarchy
Documentation¶
- CONCURRENCY.md - Threading model documentation
- docs/STATE_MACHINES.md - State machine specifications
- docs/MIGRATION.md - Error hierarchy documentation
- docs/INDEX.md - Unified documentation index
[1.4.1] - 2026-02-02¶
Added¶
- Open Claw integration with skills, workflows, and adapters
- 3 skills: primr-research, primr-strategy, primr-qa
- Lobster workflow for orchestrated research with approval gates
- New MCP resources for Open Claw integration
- Run manifest generation for audit trail
- 163 new tests for Open Claw integration
Documentation¶
- docs/OPENCLAW.md - Open Claw integration guide
[1.3.2] - 2026-01-30¶
Added¶
- Preflight validation - Research pipeline now validates all dependencies and API keys BEFORE starting expensive operations
- Checks Gemini API key validity
- Checks Google Search API key and engine ID with actual API call
- Checks Playwright browser installation
- Fails fast with clear error messages instead of failing mid-pipeline
- Input validation - Added comprehensive validation across all modules:
- AI client: temperature bounds (0.0-2.0), prompt non-empty, thinking level validation
- HTTP client: URL format validation, timeout bounds checking
- Config: AIConfig and ScrapingConfig now have
validate()methods - Thread-safe job tracking - Job tracking file operations now use file locking to prevent corruption from concurrent writes
- Atomic file writes - Job tracking uses temp file + rename pattern for crash safety
- 14 new hardening tests - Tests for input validation, error context, thread safety
Changed¶
primr doctornow tests APIs - Actually calls Google Search API to verify configuration works, not just that keys exist- Better error context - ScrapingError and SearchError now include HTTP status codes and additional context
- Improved quota detection - AI client now catches more quota error patterns (daily limit, rate limit exceeded, etc.)
- Cleanup retry logic - Temp file cleanup now retries up to 3 times with delays (helps on Windows with file locks)
- External source logging - LLM validation results now logged at INFO level so users can see why sources were accepted/rejected
Fixed¶
- Bare except handler - Fixed
except:in qa/command.py toexcept Exception:(was catching KeyboardInterrupt) - Silent validation failures - External source validation failures now logged at WARNING level
- Empty API response handling - AI client now properly handles None responses and extracts text from candidates
[1.3.1] - 2026-01-30¶
Fixed¶
- Critical: File Search Store billing leak - Stores were not being deleted because they contained documents. Fixed by implementing two-step cleanup: delete documents first, then delete store. Cleaned up 72 orphaned stores from December 2025.
- File descriptor leaks - Fixed 3 instances where
tempfile.mkstemp()file descriptors were not being closed, which could cause "too many open files" errors over time. - Database connection leaks - Fixed connection leaks in
CompanyMonitor,KnowledgeGraph, andTenantManagerwhere new SQLite connections were created on each operation but never closed. Now uses persistent connections with properclose()methods. - Silent error swallowing - Improved error logging in browser cleanup code (browsers.py) - bare
except: passpatterns now log errors at debug level for troubleshooting. - Gemini resource cleanup -
primr doctornow checks for orphaned File Search Stores and Context Caches that could be incurring costs.
Added¶
scripts/check_gemini_resources.py- Utility script to inspect and clean up Gemini resources--delete-stores --force-emptyto properly delete File Search Stores with documents--delete-cachesto remove explicit context caches- File Search Store lifecycle tests (14 tests) to prevent future billing leaks
Changed¶
- All File Search Store operations now use try/finally blocks to ensure cleanup
FileSearchStoreManager.delete_store()now properly deletes documents before store- Improved error logging when store cleanup fails
[1.3.0] - 2026-01-26¶
Added¶
- Multiple strategy document types (AI, Customer Experience, Security & Compliance, Data Fabric)
--list-strategiescommand to show available strategy frameworks--strategy-typeoption for generating specific strategy documents- Enhanced build configuration with proper version constraints
- Comprehensive security review and hardening (January 2026)
- XXE protection with secure XML parsing
- SSRF protection with URL validation
- Input validation across all user inputs
- Auto-detection of Python 3.11+ in setup wizard
Changed¶
- Python requirement updated from 3.10 to 3.11+
- Updated project description to better reflect company intelligence focus
- Improved dependency management with version constraints
- Enhanced README with clearer pipeline explanation and mode descriptions
- Consolidated scraping logic into single
fetch_web_content()function - Better documentation of scraping tier escalation
- Setup wizard now auto-restarts with correct Python version if needed
Fixed¶
- Deep Research connection drop recovery with automatic polling
- AI Strategy retry capability with
--ai-strategy-onlyflag - Windows PATH configuration in setup wizard
- Build artifact cleanup for network/sync drives
Security¶
- All critical vulnerabilities addressed (see docs/SECURITY_REVIEW_2026-01-21.md)
- Secure XML parser prevents XXE attacks
- URL validation blocks SSRF attempts
- Comprehensive input validation
[1.2.4] - 2025-12-23¶
Added¶
- Quality assessment system for generated reports
- Automatic QA scoring with color-coded grades
--qaand--qa-recentcommands for manual QA- Job recovery system for Deep Research
Changed¶
- Improved CLI output with better progress indicators
- Enhanced error messages and user guidance
[1.2.0] - 2025-12-19¶
Added¶
- AI Strategy document generation with cloud vendor customization
--ai-strategy-onlyflag for retry capability--cloud-vendoroption (azure, aws, gcp)- Batch processing with
--csvflag
Changed¶
- Unified pipeline architecture (modes are stopping points, not separate implementations)
- Improved scraping resilience with tier escalation
- Better handling of WAF-protected sites
[1.1.0] - 2025-11-15¶
Added¶
- Deep Research mode for external source validation
- Vision tier for JavaScript-heavy sites
- Automatic link discovery and selection
Changed¶
- Refactored scraping into tiered approach (HTTP → Stealth → Browser → Vision)
- Improved cost estimation with
--dry-run
[1.0.0] - 2025-10-01¶
Added¶
- Initial release
- Basic scraping and report generation
- Gemini API integration
- DOCX report output