Skip to content

feat(architecture): add the seam's enabling point, its sense and architecture styles - #16418

Merged
kyle-sexton merged 4 commits into
mainfrom
docs/architecture-vocabulary-senses-and-sources
Nov 15, 2026
Merged

kyle-sexton merged 4 commits into
mainfrom
docs/architecture-vocabulary-senses-and-sources

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

No related issue: owner decisions from a design interview on the module-design vocabulary (2026-11-14), recorded outside this repository.

Summary

The module-design vocabulary used "seam" and "adapter" without saying which of several senses it meant, and named no architecture style.

  • Seam now says it is the module-design sense, the only one an architecture finding uses, and that a finding never means a project's other senses of the word. The word is not renamed anywhere: three recorded decisions keep it.
  • docs/glossary.md gains a seam entry listing the five senses this repository defines, each by its file. That list stays out of the shipped vocabulary, which every installing repository reads.
  • Seam gains Feathers' enabling point, the place where the choice of adapter is made.
  • Adapter says it is not the Gang of Four Adapter pattern.
  • A new Architecture styles section names modular monolith and vertical slice with their sources. Which style a repository follows comes from its own standards.
  • The planning design defaults cite Steve Smith's "New is Glue" under DIP: constructing a collaborator in place is a design decision.

Fix

  • plugins/architecture/reference/vocabulary.md: the three additions above. It names no file of this repository.
  • docs/glossary.md: the seam entry.
  • plugins/architecture/skills/principles/SKILL.md: two routing rows for the new content.
  • plugins/planning/reference/design-principles.md: one sentence and one source on the DIP line.
  • plugins/architecture/evals/pr-seam-senses-and-adapter-not-gof/: one outcome case.

Verification

  • claude plugin eval on the new case at this head, 3 runs per arm: 3 of 3 passed with the plugin, 0 of 3 without it (the baseline fails the judge grader each time).
  • An earlier shape of the case used two phrase regexes and failed 1 of 6 correct replies on wording; one judge grader replaced them. After the list moved to the glossary the case scored 2 of 3, because its first question asked about a sense the shipped text no longer describes; the prompt and judge now ask what that text states.
  • validate-cases.py over plugins/architecture/evals: no FAIL; scripts/check-changelog-fragments.sh --check: valid.
  • Quotes re-read at source this session: Feathers ch. 4 (publisher's sample chapter), Smith's post (2012-04-12), Bogard's post (2018-04-19), Grzybek's primer.

Related

  • #16089 added /architecture:principles and this vocabulary file.
  • The source line for the enforcement ladder's order, decided in the same interview, ships separately: it changes a shared contract and its five copies.

🤖 Generated with Claude Code

kyle-sexton and others added 2 commits November 15, 2026 14:21
…styles

The module-design vocabulary's Seam entry says it is the module-design
sense, lists the marketplace's four other defined senses by file, and
adds Feathers' enabling point. The Adapter entry separates it from the
Gang of Four Adapter pattern. A new section names modular monolith and
vertical slice with their sources. The planning design defaults cite
Steve Smith's "New is Glue" under DIP.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…rases

Two regex graders failed one of six correct replies on wording. One
judge grader replaces them; the enabling-point and no-write checks stay
deterministic.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 15, 2026 19:31
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T19:33:15.615347Z c34062c Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 43752934690

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 41e8c291867f27263d80b945f2edaee69abdb81d: read 7 of 7 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16418 (incremental, since c34062c)

I found no security issues. This review covered only the change since c34062c8, and I read every hunk of all 7 files in that change. This lane has already reviewed an earlier head, so this review reports blocking findings only.

What changed since the last review: It rewords documentation and an eval case.

  • plugins/architecture/reference/vocabulary.md: The list of the four other senses of "seam" is gone. In its place is one sentence: a project may give the word other senses, and a finding never means those.
  • docs/glossary.md: A new seam entry lists the five senses, each linked to its file by a relative path.
  • plugins/architecture/skills/principles/SKILL.md: One routing-table row is reworded.
  • Eval case pr-seam-senses-and-adapter-not-gof:
    • The prompt and its description/expected_outcome are reworded.
    • The LLM judge's pass criterion is reworded.
    • One pass sample's fixed string is reworded.
  • Changelog fragment: Reworded to match.

What I checked:

  • Instruction surface: The vocabulary.md deletion takes out a descriptive list of links, not a rule. The routing row in SKILL.md still points to the same section. No guardrail, block list or allowlist is narrowed.
  • Eval case: allowed_tools is still [Skill, Read, Glob, Grep]. No tool grant was added and no command runs.
  • Trust controls and manifests: None of the 7 files matches a trusted-path glob. No trust control, plugin.json or marketplace.json is touched.
  • Links: The new glossary links are relative links inside the repository, in prose. Nothing fetches them.

Spend: Nothing new. The eval case's model runs were already noted in the last review, and they draw on prepaid API credits only.

critical-findings: 0

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed 41e8c291867f27263d80b945f2edaee69abdb81d: read 7 of 7 changed file(s); 0 finding(s), 0 as inline comments.

Incremental review of c34062c8..41e8c291: no findings. I read every hunk of all 7 files in scope. This lane had already reviewed an earlier head, so this review looked for blocking findings only.

What changed since the last review: the list of the marketplace's other senses of "seam" moved out of the plugin's reference/vocabulary.md and into a new seam entry in the repository's docs/glossary.md. The plugin file now just says a project may give the word other senses in its own documents, and that a finding never means those. The eval case's prompt, expected_outcome, LLM judge and passing sample now speak of "a project's own tracker seam" rather than this marketplace's. The /architecture:principles routing row and the changelog fragment were updated to match.

What I checked:

  • Glossary links: all five targets of the new entry's relative links exist at head:

    • docs/contracts/seam-phrasing/README.md
    • plugins/work-items/reference/tracker-seam.md
    • plugins/autonomy/reference/binding-seam.md
    • plugins/autonomy/reference/runner/seams.md
    • docs/migration-playbook.md

    The last review already confirmed that the #extensibility-contract-v21-the-four-seams anchor matches its heading.

  • No stale wording: nothing left under plugins/architecture/ still mentions the "four other senses" or "the marketplace's other senses" (searched with Grep). Since the shipped plugin no longer names this repository's internal files, it reads correctly in a consumer project.

  • Eval consistency: the judge's criterion 1 still matches the prompt's three questions. Its pass samples (the edited one and the unchanged "related but not the same" one) and its fail samples still sort correctly under the revised rule.

  • Changelog fragment: the minor bump still fits. Its Seam bullet now describes what ships.

  • Manifests: no plugin manifest changed, so there are no manifest lines.

  • Closing issues: the PR closes none, so there are no acceptance criteria to check.

I did not run the eval. Any pass rates the PR states are the author's claims and unverified.

Spend: the eval case still uses prepaid model credit on each plugin-eval run, the same as before (up to 10 turns and a 300-second timeout, plus one LLM judge call).

Verifier dropped 0 of 0 candidates.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 15, 2026
@kyle-sexton kyle-sexton added the do-not-merge Hard merge gate: do not merge while applied. label Nov 15, 2026
@kyle-sexton
kyle-sexton removed this pull request from the merge queue due to a manual request Nov 15, 2026
kyle-sexton and others added 2 commits November 15, 2026 14:55
…e shipped vocabulary

The list of the marketplace's four other senses of "seam" shipped to
every repository that installs the plugin. It moves to docs/glossary.md.
The vocabulary keeps one sentence: this is the module-design sense, and
a finding never means a project's other senses. The eval case asks what
the shipped text states.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…grader

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@kyle-sexton kyle-sexton changed the title feat(architecture): add seam senses, enabling point and architecture styles feat(architecture): add the seam's enabling point, its sense and architecture styles Nov 15, 2026
@kyle-sexton kyle-sexton removed the do-not-merge Hard merge gate: do not merge while applied. label Nov 15, 2026
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 15, 2026
Merged via the queue into main with commit 31689a4 Nov 15, 2026
80 checks passed
@kyle-sexton
kyle-sexton deleted the docs/architecture-vocabulary-senses-and-sources branch November 15, 2026 20:14
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant