docs: consolidate design rationale into contributing architecture and conventions - #597
Draft
gbrlcustodio wants to merge 41 commits into
Draft
docs: consolidate design rationale into contributing architecture and conventions#597gbrlcustodio wants to merge 41 commits into
gbrlcustodio wants to merge 41 commits into
Conversation
This was referenced Aug 11, 2026
gbrlcustodio
force-pushed
the
docs/architecture-principles
branch
2 times, most recently
from
August 11, 2026 23:54
32beb39 to
e2908ab
Compare
gbrlcustodio
force-pushed
the
docs/architecture-principles
branch
2 times, most recently
from
August 12, 2026 18:46
2f9e758 to
e5b7ead
Compare
This was referenced Aug 12, 2026
gbrlcustodio
marked this pull request as ready for review
August 12, 2026 18:54
gbrlcustodio
force-pushed
the
docs/architecture-principles
branch
17 times, most recently
from
August 13, 2026 14:52
7fe529d to
ceef390
Compare
packages/mcp/CLAUDE.md is a git symlink (mode 120000) whose content is the nine bytes AGENTS.md. GitHub renders a relative link to a symlink blob as the symlink, so all three links landed on a one-line file. README.md already links AGENTS.md directly. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
_auth_keychain_hints.py imports pipefy_infra.config, and packages/cli/pyproject.toml declares no pipefy-infra, so the map's claim that the CLI declares no direct edge was false. The diagram still draws no arrow, because an arrow means a declared dependency and this one is not declared. The artifact is the declaration. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The toolsets grammar omitted the four keywords that resolve_selection also accepts, so "an unknown name is a usage error" made --toolsets power look invalid. The composition root spans server and core/runtime.py, which server.py already depends on through McpRuntime.for_profile. One of the five settings-ban exceptions is justified as a startup type import, not as a per-deployment read. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The row said a deployment decides the count independently of catalog size, which is an architect's sentence, and the section commits every demand to the terms of the consumer that holds it. The consumer's goal is context. The row now parallels QR-10, since the tool list and the payload are the same kind of cost. Tool surface keeps the mechanical statement. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The six profiles are requester, operator, manager, builder, admin, and auditor. Those are personas, so the need belongs to the consumer. "Profile" cannot carry it in this document, because the word already means the local or remote deployment mode in six places and the persona selection in two. --toolsets also accepts a domain, which is a subject and not a persona, so the row names the work instead. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The word meant the local or remote deployment mode in six places and the persona-shaped tool selection in two, and the section that exists to fix a doubled name did not list it. Tool surface now says tool profile at both uses, and a bare profile means the deployment profile. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Seven sentences opened with a hand-maintained number, and each one goes stale the moment its list grows. Line 9 of the same document rejects that, and Tool surface praises the drift guard for keying to the tool names with no count written down. A count that carries a claim stays: nine tools under the power branch, eight domains, six tool profiles, and the three applications. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
…guard checks Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
The map described the denial path by its mechanism, and the mechanism was wrong: the vendor codes and the correlation id come from the debug argument, on any GraphQL error. State what a denial gives the caller instead, and leave the enrichment design out of the map. A deployment profile is the input and the transport follows from it. The glossary stated the causality backwards. Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
gbrlcustodio
force-pushed
the
docs/architecture-principles
branch
from
August 15, 2026 01:30
69ba3b8 to
1b25b68
Compare
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
gbrlcustodio
marked this pull request as draft
August 19, 2026 20:57
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The design rationale was spread across three documents. It mixed durable rules with a snapshot of module paths. A snapshot goes stale, and a coding agent reads these documents as current. A stale sentence then becomes a wrong instruction.
The form was the second problem. A contributor who asked what to do here had to read a paragraph and extract the rule from it.
Outcomes
Known gapsnames it. Both directions therefore resolve.Known gaps. Each entry names the artifact that closes it, so the entry disappears when we enable that artifact.