SharePlane User and Developer Guide
A public manual for using, operating, and extending a durable context-as-code artifact system.
1. The Manual Is Part of the Machine
SharePlane is not just a website.
It is a public-safe artifact system, a source-controlled operating model, and a durable memory layer for AI-assisted work.
The public site is what readers see. The repo is what keeps the system honest. Issues, source candidates, locked blueprints, artifacts, registries, validators, receipts, patterns, and learning logs are not side paperwork. They are the control plane.
If the work only exists in a chat, it is temporary.
If it exists in the repo with source posture, validation, receipt, and approval history, it becomes durable context.
This guide explains how SharePlane works for two audiences at once.
For users, it explains how to read SharePlane artifacts, understand their source posture, interpret claim ledgers, and recognize public-safe boundaries.
For developers, operators, collaborators, and future agents, it explains how work moves through the system without losing meaning, provenance, or approval control.
The goal is not to make AI-assisted publishing slower.
The goal is to make it harder for speed to become sloppiness wearing a nicer jacket.
2. What SharePlane Is
SharePlane is a web-first public artifact library.
It publishes durable, public-safe artifacts that humans can read and future agents can inspect without digging through chat history.
SharePlane is also a context-as-code operating system.
That means the durable part of the work is not the model session, the prompt, the chat, or the tool interface. The durable part is the repo-held context:
- issues
- source candidates
- locked blueprints
- public artifact pages
- site registry metadata
- pattern registry metadata
- validators
- implementation receipts
- public reader receipts
- learning logs
- reusable patterns
The method is simple:
Ideas become candidates.
Candidates become locked blueprints.
Locked blueprints become scoped implementation work.
Implementation work becomes validated artifacts.
Validated artifacts go through UAT.
Approved artifacts are merged with exact-head discipline.
Receipts preserve what happened.
Learning updates the system.
Patterns capture what should be reused.
That loop is SharePlane.
The public artifact is the surface.
The repo is the memory.
The human owner is the authority layer.
The model is a participant, not the institution.
3. What SharePlane Is Not
SharePlane is not a CMS.
It is not a backend platform.
It is not an analytics product.
It is not a RAG system.
It is not a vector database.
It is not a runtime AI application.
It is not a package or build pipeline.
It is not a place to dump raw transcripts, private source packets, screenshots, local staging files, confidential notes, employer material, regulated records, patient data, vendor documents, account details, or implementation secrets.
SharePlane is intentionally boring in the parts that should be boring.
Static files are boring.
Source control is boring.
Validators are boring.
Receipts are boring.
Exact-head merge discipline is boring.
That is the point.
The interesting part is the thinking. The infrastructure exists so the thinking does not evaporate, mutate, or leak private material into public artifacts.
SharePlane does not try to make AI magical.
It tries to make AI-assisted work inspectable.
A civilization-threatening ambition, apparently.
4. The SharePlane Method Is Portable
SharePlane is not defined by a single model, provider, editor, repository host, or automation tool.
The current implementation uses Tony, ChatGPT, Codex, GitHub, static HTML, validators, receipts, and a pattern registry. That is the current stack. It is not the method.
The method is the operating grammar underneath the stack.
At its simplest, SharePlane separates five jobs:
1. Owner / Judge
2. Interpreter / Architect
3. Executor / Implementer
4. Verifier / Validator
5. Repository / Durable Context Plane
The current SharePlane implementation maps those jobs this way:
- Tony is the Owner / Judge.
- ChatGPT is the Interpreter / Architect.
- Codex is the Executor / Implementer.
- Validators, UAT, receipts, and exact-head merge discipline are the verification system.
- GitHub is the durable context plane.
- The static site is the public artifact surface.
Those assignments are implementation choices.
The same method can be implemented with other tools:
- ChatGPT, Claude, Gemini, local LLMs, or future frontier models can serve as Interpreter / Architect if they preserve source posture, claim posture, public-safe boundaries, and human judgment.
- Codex-like agents, repo agents, scripts, human implementers, or local automation can serve as Executor / Implementer if they only perform scoped mechanical work after the blueprint is locked.
- GitHub, GitLab, local Git, self-hosted Git, or another durable source-controlled system can serve as the Repository / Durable Context Plane.
- Static HTML, Markdown-rendered sites, docs portals, or other public-safe publishing surfaces can serve as the Artifact Layer if they preserve provenance, receipts, validation, and reader clarity.
- Local LLMs can participate when repo-held context, source boundaries, and role constraints are strong enough to prevent drift.
The method survives provider changes because it does not trust the provider to be the system of record.
The repo is the system of record.
The model session is temporary.
The artifact is public.
The receipt is memory.
The validator is a guardrail.
The owner is accountable for meaning.
This distinction matters because AI tools change constantly. Model names change. Interfaces change. Usage limits change. Context windows grow. Local models improve. Repo agents become more capable. Providers rename products because apparently stable naming was too much civilization to ask for.
SharePlane should absorb those changes without losing its operating discipline.
A better model can improve judgment support. It does not erase the need for source control.
A faster executor can reduce implementation time. It does not earn permission to author.
A local model can improve sovereignty. It does not automatically improve truth, taste, or safety.
A new provider can become useful. It does not become the authority layer.
The authority layer is the locked process:
intent -> source/candidate -> human judgment -> locked blueprint -> scoped implementation -> validation -> UAT -> exact approval -> receipt -> learning -> pattern promotion
Tools may change.
The method should not.
5. Preferred Working Model
SharePlane uses a deliberate split between thinking and file mutation.
The preferred way of working is simple:
Tony and ChatGPT do the thinking.
Codex does the mechanical repo work after the thinking is locked.
That split is not ceremony. It is a control boundary.
Tony owns judgment. That includes thesis, intent, source authority, claim posture, public-safe boundary, design direction, visual posture, pattern decision, Creative Lock, UAT, and merge authorization.
ChatGPT helps Tony turn that judgment into a precise operating package. That includes source intake, interpretation, architecture, structure, writing, issue formulation, semantic review, acceptance criteria, validation expectations, UAT translation, and eventual Codex handoff prompts.
Codex does not own judgment.
Codex does not author.
Codex does not design.
Codex does not architect.
Codex does not compress rich writing into a dashboard because it got bored.
Codex does not reinterpret source posture, claim posture, privacy posture, or public-safe boundaries.
Codex does not decide that a guide should become shorter, prettier, broader, narrower, more generic, more exciting, more marketable, or more AI-native.
Codex implements locked instructions.
Codex may inspect the repo, create branches, place locked copy, edit scoped files, update scoped registry entries, write validators, write receipts, run validation, open draft pull requests, and report exact results.
Codex must stop and report if the blueprint is incomplete, contradictory, unsafe, stale, ambiguous, or impossible to implement without changing meaning.
The operating principle is this:
Meaning and file mutation are deliberately separated.
That is the whole trick.
It keeps the system fast without making it stupid.
6. Tool, Repo, and Agent Configuration
SharePlane is portable, but portability does not mean vague.
A durable AI-assisted artifact system needs explicit configuration boundaries. Tools should know their role. Repos should know what they store. Agents should know when to stop. Public artifacts should know what not to reveal.
The current SharePlane implementation uses a specific stack:
- human owner
- interpretive AI assistant
- repo execution agent
- GitHub repository
- static public site
- site registry
- pattern registry
- validators
- receipts
- learning logs
- issue and pull request workflow
That stack can change.
The configuration pattern should not.
Configuration principle
Configure the system around responsibilities, not products.
The method needs these durable roles:
- Owner / Judge
- Interpreter / Architect
- Executor / Implementer
- Verifier / Validator
- Repository / Durable Context Plane
- Public Artifact Surface
- Learning / Pattern Memory
A tool should be assigned to a role only if it can operate within that role’s boundaries.
A frontier model may be useful as Interpreter / Architect.
A local LLM may be useful for private drafting, repo-aware reasoning, or sovereignty-sensitive workflows.
A repo agent may be useful as Executor / Implementer.
A script may be useful as Verifier / Validator.
A Git repository may be useful as Durable Context Plane.
A static site may be useful as Public Artifact Surface.
None of those tools becomes the authority layer.
The authority layer is the locked process and the human owner’s approval.
Current SharePlane example
In the current SharePlane stack:
- Tony owns judgment.
- ChatGPT helps interpret, structure, write, reason, and prepare locked packages.
- Codex performs scoped repo implementation after lock.
- GitHub stores issues, pull requests, files, validators, registries, receipts, and learning logs.
- The static site publishes public artifacts.
- Validators check deterministic boundaries.
- Receipts preserve execution memory.
- UAT accepts or rejects the result.
- Exact-head merge discipline prevents approval drift.
This current implementation is useful because it makes the control boundaries visible.
It is not sacred.
It is not provider-locked.
It is not cloud-only.
It is not OpenAI-only.
It is not Codex-only.
It is one working implementation of a portable method.
Agent entrypoint
A repo that expects AI-assisted work should provide an obvious agent entrypoint.
For SharePlane, the active guidance currently lives in repo-side agent documents.
A future repo hygiene improvement may add a root-level AGENTS.md or equivalent entrypoint that points agents to the authoritative workflow docs.
The purpose of an agent entrypoint is not to make agents autonomous.
The purpose is to prevent agents from guessing.
An agent entrypoint should tell any executor:
- what the system is
- what the executor may do
- what the executor must not do
- where workflow rules live
- where artifact standards live
- where validators live
- where receipts live
- which files are authority
- which files are presentation
- when to stop and report
This should be boring and explicit.
Boring and explicit is how a repo tells a tool, “No, you may not become creative because you found a keyboard.”
Tool configuration pattern
A SharePlane-style system should configure tools by role.
Owner / Judge
The owner decides:
- intent
- thesis
- source authority
- claim posture
- public-safe boundary
- design posture
- pattern posture
- acceptance criteria
- UAT
- merge authorization
This role should not be delegated to an executor.
Interpreter / Architect
The interpreter helps with:
- source intake
- synthesis
- architecture
- writing
- structure
- semantic review
- issue formulation
- acceptance criteria
- correction translation
- implementation handoff prompts
This role may be performed by ChatGPT, Claude, Gemini, a local LLM, or another reasoning system, but only if the system preserves the owner’s authority and the repo’s source-controlled context.
Executor / Implementer
The executor performs mechanical work:
- inspect files
- create branches
- place locked copy
- edit scoped files
- update scoped registries
- create validators
- create receipts
- run validation
- open draft pull requests
- report exact results
The executor does not author.
The executor does not design.
The executor does not architect.
The executor does not decide meaning.
The executor does not compress rich guide copy into a short summary because the implementation would be easier.
Ease is not governance.
Verifier / Validator
The verifier checks deterministic boundaries:
- required files
- required sections
- registry schema
- pattern lifecycle consistency
- prohibited material exclusions
- public-safe markers
- validation commands
- no unscoped backend or dependency additions
- no unscoped registry mutation
The verifier does not replace UAT.
A green validator means the floor held.
It does not mean the room is worth living in.
Repository / Durable Context Plane
The repository stores durable context:
- issues
- candidates
- locked blueprints
- artifacts
- registries
- validators
- receipts
- standards
- guides
- patterns
- learning logs
The repository should be the system of record.
Chat sessions are useful, but they are not durable authority unless their decisions are captured into repo-visible locked context.
Public Artifact Surface
The public artifact surface presents the approved result.
It should include the reader-facing guide, artifact, receipt, source posture, caveats, and related links.
It should not expose private source material, local paths, internal workflow debris, raw packets, account data, rejected prompt history, or implementation secrets.
Local LLM configuration
Local LLMs can participate in SharePlane-style workflows.
They are useful when the work benefits from:
- local privacy
- lower operating cost
- sovereignty
- offline resilience
- private drafting
- repeatable local workflows
- repo-aware review
- source packet inspection before public abstraction
A local LLM should still be assigned a role.
A local model used as Interpreter / Architect may help reason through structure, source posture, candidate staging, or draft language.
A local model used as Executor / Implementer must obey the same locked-scope rules as Codex.
A local model used as Verifier may help review deterministic outputs, but formal validators should still be executable scripts where practical.
Local does not automatically mean safe.
Local does not automatically mean correct.
Local does not automatically mean public-safe.
Local means the compute location changed.
The governance requirement did not.
Recommended repo configuration
A SharePlane-style repo should include these control surfaces:
README.mdfor project orientation- agent entrypoint such as
AGENTS.mdordocs/agent/AGENT_INDEX.md - workflow decision tree
- lane contracts
- artifact standard
- implementation prompt standard
- visual prompt suite standard
- provenance and receipt standard
- site registry
- pattern registry
- focused validators
- workflow receipts
- learning logs
- negative-pattern receipts
- public artifact pages
- guide or handbook documentation
The file names can differ.
The control surfaces should not.
A repo does not need to copy SharePlane’s exact folder structure to use the method.
It does need a durable place for:
- what the system is
- how work is routed
- who owns meaning
- who may mutate files
- what validators enforce
- what receipts preserve
- what patterns govern reuse
- when executors must stop
Public-safe configuration boundary
Public documentation may explain the method.
Public documentation may reference repo paths when those paths are part of the public artifact system.
Public documentation must not expose:
- raw source packets
- private staging paths
- transcripts
- screenshots
- account details
- private notes
- implementation secrets
- local machine paths
- regulated records
- patient data
- vendor documents
- employer-specific systems
- security posture
- audit posture
- operational roadmaps
- real incidents
Private implementation details belong in private receipts, private staging, or local operator documentation.
The public manual should teach the operating pattern without leaking the wiring closet.
Configuration anti-patterns
Avoid these patterns:
- no agent entrypoint
- no lane decision tree
- no clear role boundary
- no source posture rules
- no public-safe gate
- no registry mutation scope
- no pattern lifecycle
- no validators
- no receipts
- no UAT
- no exact-head merge discipline
- executors allowed to author
- implementation agents allowed to design
- public artifacts exposing internal workflow debris
- local LLMs treated as magically safer because they are local
- provider-specific workflow assumptions baked into the method
The tool stack can change.
The control boundaries should remain.
7. How to Read a SharePlane Artifact
A SharePlane artifact is not just an article, page, diagram, or visual exercise.
It is a public-safe unit of thinking with provenance, claim posture, validation posture, and reader-facing boundaries.
A mature artifact usually contains:
- a title and subtitle
- a clear thesis
- a source or provenance explanation
- a public-safe boundary
- a structured argument or teaching model
- claim, evidence, and caveat separation
- related artifacts
- visual prompt suite or visual teaching layer when useful
- public reader receipt
- registry metadata
- implementation receipt in the repo
- focused validator
Not every artifact needs the same shape. SharePlane has shared governance, not one skin stretched over every subject like a cheap CMS theme with ambitions.
Some artifacts are article-led. The prose is the product. Visual modules support the argument.
Some artifacts are teaching-led. Diagrams, matrices, cards, and structured models carry more of the instructional load.
Some artifacts are source-derived. They need stronger source identity, source-role explanation, claim posture, caveats, and public-safe exclusions.
Some artifacts are pattern-facing. They demonstrate or explain a reusable method, but they do not become pattern authority unless the pattern registry is explicitly updated later.
When reading a SharePlane artifact, look for five things.
First, identify the artifact’s purpose.
Is it explaining a concept, teaching a method, publishing a source-derived interpretation, documenting a pattern, or showing an operating model?
Second, identify the source posture.
Is the artifact based on public sources, repo-derived operating rules, synthetic examples, owner-approved thesis, public documentation, expert-source interpretation, or some combination of those?
Third, identify the claim posture.
Is the artifact making verified factual claims, source-attributed claims, architectural judgments, teaching interpretations, caveats, or explicit non-claims?
Fourth, identify the boundary.
A good artifact tells you what it is not claiming. That matters more than most people admit, which explains several centuries of meetings.
Fifth, inspect the receipt.
The public receipt should explain the artifact’s posture, source boundary, validation posture, and public-safe exclusions without dumping internal implementation mechanics onto the reader.
A SharePlane artifact should make the reader smarter about both the subject and the confidence boundary around the subject.
If a page sounds confident but hides source posture, claim posture, validation posture, or caveats, it is not behaving like a mature SharePlane artifact.
It is just content with a nice shirt.
8. Source, Claims, Caveats, and Receipts
SharePlane separates thesis, source, evidence, interpretation, and caveat.
That separation is one of the core disciplines of the system.
A source can support a claim without becoming the origin of the thesis.
A thesis can be owner-originated without pretending that a citation invented it.
A public source can be authoritative for its own behavior without becoming proof of every conclusion built around it.
A vendor claim can be useful without becoming neutral.
An expert statement can be important without becoming universal proof.
A repo-derived claim can be strong for SharePlane operating behavior and weak for external-world claims.
This is why SharePlane uses visible claim posture.
Common claim postures include:
- verified public-source fact
- source claim
- reported finding
- current-as-of product or pricing claim
- official guidance posture
- commercial or vendor ecosystem signal
- owner-approved thesis
- architectural judgment
- teaching interpretation
- caveat
- unresolved claim
- softened claim
- excluded claim
- prohibited strengthening
The point is not to make every page painfully academic.
The point is to stop unsupported confidence from breeding in the dark.
Caveats are not weakness. They are part of the artifact’s honesty model.
A caveat can say:
- this source is useful but not neutral
- this claim is current only as of a date
- this conclusion is architectural judgment, not settled fact
- this artifact is educational, not legal or compliance advice
- this example is synthetic
- this source supports context but not the core thesis
- this artifact does not describe a specific company, client, employer, system, vendor stack, incident, roadmap, or implementation
Receipts preserve the execution memory.
A public reader receipt should tell the reader what kind of artifact they are reading, what source posture it uses, what was excluded, how it was validated, and where the artifact sits in the SharePlane system.
A committed implementation receipt should record what changed, which validators ran, what passed, what was intentionally excluded, what boundaries were preserved, and what remains out of scope.
The public receipt and implementation receipt have different jobs.
The public receipt helps readers.
The implementation receipt helps operators.
Do not dump branch names, local paths, token drama, temporary files, rejected prompt versions, or implementation detritus into the public artifact.
That material belongs in PRs, issues, validators, receipts, or the nearest digital landfill.
9. How Work Moves Through the System
SharePlane work moves through a controlled lifecycle.
The lifecycle exists to keep ideas from jumping directly from chat into public artifact pages without source posture, claim posture, review, validation, or approval.
The normal path is:
intent -> source or candidate -> locked blueprint -> implementation issue -> branch -> draft PR -> validation -> UAT -> correction if needed -> exact-head merge -> receipt -> learning -> pattern promotion if reusable
Each stage has a job.
Intent
Intent starts the work.
Intent can be a rough idea, source link, critique, operating observation, article thesis, visual prompt direction, workflow problem, repo hygiene issue, or publication candidate.
Intent is not implementation authority.
A source link is not a blueprint.
A strong opinion is not a locked artifact.
A chat fragment is not a repo-safe instruction.
This is where many systems fail. They confuse “interesting” with “ready,” then act shocked when the output looks like it was assembled by a committee of caffeinated interns.
Source or Candidate
The source or candidate stage makes the material inspectable.
This stage identifies source type, public/private posture, likely lane, claim posture, unresolved questions, public-safe boundary, future artifact shape, and non-goals.
A candidate may live in a repo file, issue, chat-developed package, source packet, or other controlled staging surface.
Candidate staging is not publication.
Candidate staging is not permission for Codex to write public copy.
Candidate staging is where the system decides whether the work is safe, coherent, useful, and worth advancing.
Locked Blueprint
The locked blueprint is where meaning becomes implementation-ready.
This is the Creative Lock or Guide Lock layer.
It defines thesis, section order, source posture, claim posture, public-safe boundary, design posture, visual direction, copy expectations, acceptance criteria, validator expectations, and stop/report rules.
This is human-side work.
Tony and ChatGPT own it.
Codex does not create it.
Codex does not infer it.
Codex does not improve it.
Codex receives it only after it is locked.
Implementation Issue
The implementation issue turns the locked blueprint into scoped repo work.
A good implementation issue says:
- what to create or change
- what source is authoritative
- what files are allowed
- what files are forbidden
- what registry changes are scoped
- what pattern changes are scoped or forbidden
- what validators must run
- what receipt must be created
- what UAT must prove
- what stop/report conditions apply
- whether a draft PR is expected
- whether merge is forbidden until explicit approval
An implementation issue does not invite Codex to author.
It gives Codex a controlled mechanical job.
Branch and Draft PR
Codex creates a branch from the approved baseline and performs the scoped implementation.
The draft PR is the review container.
Draft PR does not mean placeholder.
Draft PR does not mean “open an empty PR and wait for meaning to arrive by courier pigeon.”
Draft PR means implementation is completed, validators have run, receipts exist, and the work is ready for review while still unmerged.
The PR remains draft unless the owner explicitly authorizes otherwise.
No automerge.
No quiet merge.
No optimistic merge because the CI lights looked friendly.
Validation
Validators check deterministic rules.
They can prove that files exist, required sections appear, JSON parses, registry entries follow schema, prohibited material is absent, pattern registry relationships are reciprocal, and required receipt or footer structures exist.
Validators cannot prove taste.
Validators cannot prove truth.
Validators cannot prove legal sufficiency.
Validators cannot prove public meaning.
Validators cannot prove visual quality.
Validators cannot prove that a claim should have been made.
Validators are guardrails, not judgment.
A page can pass validators and still fail UAT. This is not a contradiction. It is the entire reason humans are still unfortunately in the loop.
UAT
UAT is owner review.
Tony reviews meaning, source posture, visual posture, section rhythm, public-safe boundary, artifact usefulness, and whether the artifact actually does what it was supposed to do.
UAT can reject a validator-passing artifact.
UAT can require correction.
UAT approval attaches to a specific branch head.
If the branch changes after approval, approval must be rechecked against the new head.
Correction
Correction work must also be locked.
A correction pass should say exactly what is wrong, what must change, what must not change, which source or UAT note controls the correction, and how the correction will be validated.
Codex applies the correction mechanically.
Codex does not reinterpret the rejection into a new design direction.
Codex does not use a correction pass as an invitation to remodel the kitchen.
Exact-Head Merge
Merge happens only after explicit approval.
The branch head SHA must be re-read immediately before merge.
The merge must use exact-head protection.
If the branch head changed, prior approval is invalid until reviewed again or explicitly re-approved against the new head.
This is not paranoia. It is basic control discipline wearing steel-toed boots.
Receipt and Learning
The receipt records what happened.
It preserves changed files, validation results, scoped boundaries, excluded material, UAT posture, registry changes, pattern posture, and closeout facts.
Learning logs capture reusable lessons.
Negative-pattern receipts capture failure classes.
If a workflow mistake repeats, the system should learn from it mechanically, not rely on someone remembering the pain later like a campfire story for exhausted engineers.
Pattern Promotion
Not every successful artifact becomes a pattern.
A pattern is reusable authority.
An artifact can demonstrate a route, but pattern authority belongs in the pattern docs and pattern registry when formally promoted.
Pattern promotion requires its own decision.
No artifact should accidentally become a standard because it looked useful once.
That is how bad habits get promoted into architecture.
10. Repo Structure and Control Surfaces
SharePlane uses the repo as its durable context plane.
The public site is only one surface. The repo also holds the operating memory, standards, source posture, validators, receipts, pattern rules, workflow lessons, and implementation history.
That distinction matters.
A public page tells the reader what the artifact says.
The repo tells the operator why the artifact exists, where its authority came from, what was validated, what was excluded, what pattern it may relate to, and what should happen next.
The exact repo structure can evolve, but the control surfaces should remain clear.
Public artifact surface
Public artifacts live under the site surface.
Typical path:
site/pages/<artifact-slug>/index.html
A public artifact is the reader-facing result. It should be coherent on its own. It should not require the reader to understand GitHub issues, branch names, validator internals, source packet mechanics, or implementation receipts.
The artifact may include a public receipt, source notes, related artifacts, claim posture, caveats, and visual prompt suites when useful.
It should not expose private workflow debris just because the repo knows about it.
Site registry
The site registry controls artifact discoverability.
Typical path:
site/registry.json
The registry tells the public catalog what artifacts exist, where they live, how they should be categorized, how they should be summarized, whether they are featured, what their source posture is, and what validation posture they carry.
Registry edits are controlled changes.
A publication issue must explicitly scope registry mutation.
Codex must not casually rewrite unrelated registry entries because it noticed formatting opportunities. That is how “small cleanup” turns into metadata vandalism with a commit hash.
Pattern registry
The pattern registry controls reusable method authority.
Typical path:
docs/patterns/pattern-registry.json
The pattern registry is separate from the site registry.
The site registry governs public artifacts.
The pattern registry governs reusable patterns.
An artifact can demonstrate a pattern without becoming pattern authority.
A pattern becomes authority only when a scoped pattern-promotion issue updates the pattern docs and pattern registry.
Pattern documents
Pattern documents describe reusable standards.
Typical path:
docs/patterns/
A pattern document explains when to use a pattern, when not to use it, what structure it requires, what validators should check, what visual or semantic posture it expects, and how it relates to prior or superseded patterns.
Pattern docs should not be silently rewritten during artifact publication unless the issue explicitly scopes pattern work.
Agent and workflow documents
Agent and workflow documents tell future operators and agents how to behave before touching the repo.
Typical paths include:
docs/agent/AGENT_INDEX.md
docs/agent/WORKFLOW_DECISION_TREE.md
docs/agent/ARTIFACT_LANE_CONTRACTS.md
These docs reduce dependence on chat memory. They are part of the operating system.
If a workflow lesson changes how SharePlane should operate, the relevant guide, agent doc, pattern doc, standard, or learning log must be updated.
Guide documents
Guide documents explain the system in human-readable form.
Typical path:
docs/guides/
The docs-side handbook is the internal source candidate for this public guide. The public guide is the reader-facing manual.
The docs-side guide may include repo-specific operating detail. The public guide should preserve the method while removing unnecessary internal mechanics from the reader surface.
Validators
Validators enforce deterministic rules.
Typical path:
validation/scripts/
Focused validators protect specific artifacts, patterns, registries, and workflow standards.
Validators should check what machines can check:
- files exist
- required text appears
- JSON parses
- schema expectations are met
- registry changes are scoped
- prohibited source material is absent
- required sections remain present
- pattern lifecycle relationships stay consistent
- runtime, backend, analytics, package, or dependency additions are not introduced accidentally
Validators do not replace judgment.
They keep the floor from collapsing while humans inspect the ceiling.
Receipts
Receipts preserve execution memory.
Typical paths include:
docs/workflows/receipts/
docs/workflows/learning/
A receipt records what changed, what validation ran, what passed, what was excluded, what boundaries were preserved, and what still needs attention.
A learning log records reusable process lessons.
A negative-pattern receipt records failure classes so the system can avoid repeating them.
Memory should not depend on a human remembering what went wrong three chats ago while also juggling four artifacts, two repo branches, and the usual modern carnival of digital inconvenience.
Issues and pull requests
Issues define scope.
Pull requests deliver scoped change.
An issue should clarify lane, source authority, boundaries, acceptance criteria, validators, receipts, registry scope, stop/report conditions, and merge posture.
A pull request should show what changed, what validation ran, what boundaries were preserved, and whether the work is ready for UAT.
Draft PR means review container.
It does not mean placeholder.
It does not mean merge queue.
It does not mean Codex gets to improvise because a branch exists.
11. Registry and Catalog Behavior
SharePlane uses registry metadata to make public artifacts discoverable and inspectable.
The registry is not decorative.
It is the structured public memory of the artifact catalog.
The site registry answers these questions:
- What artifacts exist?
- Where do they live?
- What are they called?
- Who are they for?
- What topics do they cover?
- What source posture do they carry?
- What validation posture do they carry?
- What credibility boundary should readers see?
- Which artifacts are featured?
- Which artifacts are recent?
A mature artifact registry entry usually includes:
- stable id
- slug
- title
- subtitle
- type
- format
- status
- privacy posture
- public path
- created date
- updated date
- topic family
- topics
- tags
- audience
- source profile
- validation posture
- credibility posture
- summary
- description
- disclaimer
The registry is public-facing metadata, not private implementation memory.
It should not contain local staging paths, private notes, source packet internals, transcript dumps, employer details, account data, or implementation secrets.
Featured artifacts
Featured artifacts are intentionally controlled.
The rule is simple:
featured: truemakes an artifact eligible.featuredRankcontrols ordering.- Lower rank appears first.
- Missing rank behaves as lower priority.
- Tie-breakers use updated dates, then created dates.
- The front page displays the first three featured artifacts.
This is not random.
This is not popularity scoring.
This is not analytics-driven personalization.
This is not “whatever the last script happened to sort first.”
Featured placement is editorial control.
When featuring an artifact, update only the scoped registry entry, choose the rank deliberately, validate the JSON, run the catalog and taxonomy validators, and confirm unrelated entries were not changed.
Recent artifacts
Recent artifact selection should be deterministic.
The catalog should sort by the current repo-defined metadata rules, not by guesswork or visual preference.
If created dates tie, updated dates or defined fallback behavior should resolve order according to the site logic.
Do not manually rearrange public cards in generated output as the authority layer.
The registry is authority.
Rendered catalog output is presentation.
Treating presentation as authority is how systems slowly become haunted.
Registry mutation discipline
Registry changes must be explicitly scoped.
Allowed examples:
- adding a new artifact entry during publication
- updating one artifact’s featured posture
- correcting one artifact’s metadata after UAT
- updating registry schema fields when separately scoped
- marking an artifact archived when separately scoped
Forbidden examples unless explicitly authorized:
- rewriting unrelated artifact summaries
- reordering unrelated entries
- weakening disclaimers
- removing source posture
- changing credibility posture without review
- changing featured status across multiple artifacts
- mutating pattern registry while publishing an artifact
- cleaning up metadata opportunistically during unrelated work
Registry mutation is governance work.
Treat it like a controlled change, not a formatting chore.
12. Pattern Registry and Pattern Lifecycle
Patterns are reusable operating authority.
A pattern is stronger than an example.
An artifact can show a useful approach. A pattern tells future work when and how to reuse that approach.
That distinction matters because examples are contextual. Patterns are prescriptive.
SharePlane keeps pattern authority in pattern documents and the pattern registry.
The public pattern catalog may display pattern metadata, but the catalog is not the authority layer.
The pattern document defines the standard.
The pattern registry records the reusable metadata.
The artifact demonstrates the pattern.
Each job is different. Blurring them is how one good-looking page accidentally becomes doctrine because nobody wanted to write a standard.
Pattern lifecycle statuses
Pattern statuses make reuse posture visible.
Common lifecycle statuses include:
candidatedraftlockedsupersededdeprecatedarchived
A candidate pattern is proposed but not yet authority.
A draft pattern is active but still changing.
A locked pattern is approved and should not silently change.
A superseded pattern has been replaced for new work but remains available for history.
A deprecated pattern is retained for reference but no longer recommended.
An archived pattern is historical record.
The status tells operators how to treat the pattern.
It should not be decorative metadata.
Supersession
Patterns evolve.
When a new pattern replaces an older one, the relationship should be explicit.
Useful lifecycle fields include:
supersedessupersededByreplacementPolicy
supersedes identifies older patterns the new pattern replaces.
supersededBy identifies the newer pattern that replaces the older one.
replacementPolicy explains what future work should use and why the older pattern remains.
Do not delete history just because a newer pattern exists.
Do not present superseded patterns as equal current choices.
Do not create duplicate current patterns when the real action is a version update.
Version drift is already a plague. It does not need help from the documentation.
Pattern promotion
Pattern promotion requires a decision.
A successful artifact may create pattern evidence.
It does not automatically create pattern authority.
Before promoting a pattern, the system should ask:
- What problem does this pattern solve?
- Which artifact or artifacts proved it?
- What should future work reuse?
- What should future work avoid?
- What are the required sections or structures?
- What are the stop/report conditions?
- What validators should protect it?
- Does it supersede an existing pattern?
- Should the older pattern remain current, superseded, deprecated, or archived?
- Is this truly a reusable method or just one successful artifact?
Pattern promotion is a governance lane.
It should not be smuggled into artifact publication.
Manual / operator guide pattern posture
This public guide may become the first reference candidate for a future manual/operator-guide web pattern.
That pattern should not be formally registered just because this guide exists.
The guide can prove the route.
A later pattern-promotion issue can decide whether the route becomes reusable authority.
Until then, the guide is a public artifact and pattern candidate evidence, not a formal pattern registry entry.
This prevents a familiar little disaster: one good page gets mistaken for a permanent standard before anyone has tested whether the pattern actually generalizes.
13. Validators and Receipts
SharePlane uses validators and receipts because memory is fragile and enthusiasm is dangerous.
A validator is a deterministic check.
A receipt is an execution record.
Together, they create a minimum evidence trail around public artifact work.
They do not replace judgment. They make judgment reviewable.
What validators prove
Validators prove machine-checkable facts.
They can check that:
- required files exist
- required sections are present
- required anchors or labels appear
- JSON parses
- registry entries follow expected structure
- pattern registry lifecycle fields are consistent
- prohibited source material is absent
- scoped registry mutation stayed scoped
- required public footer receipt language exists
- required source posture markers remain visible
- no backend, runtime, database, analytics, package, or dependency additions were introduced
- generated or rendered catalog surfaces match source registry metadata
A validator should be boring, strict, and repeatable.
That is its entire charm.
What validators cannot prove
Validators cannot prove that an artifact is good.
They cannot prove:
- truth
- taste
- strategy
- design quality
- public usefulness
- legal sufficiency
- compliance sufficiency
- regulatory correctness
- source neutrality
- claim appropriateness
- semantic acceptance
- whether the page says what Tony meant
A validator can prove the required section exists.
It cannot prove the section should have been written that way.
A validator can prove a disclaimer appears.
It cannot prove the disclaimer is sufficient for the risk.
A validator can prove a visual prompt suite exists.
It cannot prove the prompts are visually strong, useful, or worth publishing.
This is why UAT exists.
Validators are necessary.
They are not sufficient.
Focused validators
A focused validator protects a specific artifact, pattern, or workflow rule.
Focused validators should be created when the work introduces important structure that future edits must not accidentally remove.
Examples:
- a source-derived artifact needs a required claim/evidence/caveat ledger
- a public guide needs required user and developer sections
- a pattern page needs required lifecycle fields
- a registry change needs scoped mutation checks
- a workflow rule needs durable language preserved across docs
- a visual prompt suite needs required prompt variants and accessibility notes
Focused validators should check the contract, not the prose style.
They should be strict enough to catch regression but not so brittle that punctuation becomes a governance incident.
Humanity has enough fake emergencies.
Receipts
A receipt records what happened.
A good implementation receipt includes:
- issue number or controlling scope
- PR number when available
- branch name
- exact head SHA when relevant
- changed files
- source authority used
- public artifact path
- registry changes
- validator path
- validation commands and results
- public-safe boundary
- prohibited material exclusions
- pattern posture
- UAT posture
- merge posture
- unresolved risks
- closeout facts
Receipts matter because work moves fast.
Without receipts, every future review becomes archaeology.
With receipts, the system can answer:
- What changed?
- Why did it change?
- What was validated?
- What was intentionally excluded?
- What authority controlled the work?
- What boundaries were preserved?
- What remains out of scope?
- What should future operators know?
That is not paperwork.
That is memory with a file path.
Public receipt versus implementation receipt
SharePlane separates public reader receipts from implementation receipts.
The public reader receipt belongs in the artifact.
It should tell the reader:
- what kind of artifact this is
- what source posture it uses
- what it does not claim
- what was excluded
- how it was validated at a high level
- where related public context lives
The implementation receipt belongs in the repo.
It can include:
- issue numbers
- PR numbers
- branches
- commit SHAs
- validation logs
- scoped implementation details
- exact changed files
- merge facts
- internal closeout notes
Do not confuse these two receipts.
The reader does not need branch trivia.
The operator does.
The public page should not become a landfill of implementation exhaust.
Learning logs and negative-pattern receipts
SharePlane should learn from friction.
When a failure teaches a reusable lesson, capture it.
When a correction reveals a repeated failure mode, capture it.
When Codex compresses rich prose, confuses draft PR posture, oversteps source posture, creates dashboard sludge, skips public receipt quality, or treats a candidate like a publication ticket, capture it.
A negative-pattern receipt is not shame theater.
It is a warning label for future runs.
The goal is not to remember pain.
The goal is to mechanize the lesson so the same avoidable failure does not return wearing a different branch name.
14. UAT and Exact-Head Merge Discipline
UAT is the human acceptance gate.
Validators check the floor.
UAT checks whether the artifact should exist in its current form.
Tony performs UAT for meaning, source posture, visual quality, public-safe boundary, artifact usefulness, and acceptance against the locked intent.
UAT is not optional.
A public artifact can pass every validator and still fail.
That is not a defect in the process. That is the process working.
UAT review areas
UAT should inspect:
- thesis accuracy
- semantic posture
- source posture
- claim strength
- caveat quality
- public-safe boundary
- visual quality
- mobile layout
- desktop layout
- navigation behavior
- reading rhythm
- related artifact relevance
- visual prompt suite usefulness
- public footer receipt quality
- whether the artifact preserves the locked intent
A guide or article should be read like a reader will read it, not merely inspected like a file diff.
If the artifact is supposed to teach, it must teach.
If it is supposed to argue, it must argue.
If it is supposed to guide, it must guide.
If it merely survives validation, congratulations, it has achieved the moral status of a parking meter.
Visual UAT
Visual UAT matters because SharePlane artifacts are public surfaces.
A page should not look like a generic AI dashboard, a default docs template, a collapsed spreadsheet, or a SaaS landing page that discovered gradients five minutes ago.
Visual review should check:
- first viewport quality
- section rhythm
- typography
- spacing
- contrast
- mobile overflow
- navigation height
- prompt readability
- footer readability
- whether visual modules support the argument
- whether decorative structures overwhelm the reading experience
Visual modules are allowed.
Visual replacement of thinking is not.
Semantic UAT
Semantic UAT checks whether the artifact says the right thing.
It asks:
- Is the thesis right?
- Is the source posture right?
- Are claims too strong?
- Are caveats visible?
- Is the public-safe boundary clear?
- Does the artifact imply something it should not?
- Did implementation preserve the locked writing?
- Did any mechanical change alter meaning?
- Did the artifact keep Tony’s intended pattern of working intact?
Semantic UAT overrides validator success.
The validator is not offended.
It is a script.
It will recover.
Correction passes
A failed UAT review should produce a controlled correction pass.
A correction pass should define:
- what failed
- where it failed
- what must change
- what must not change
- what source or UAT note controls the correction
- what acceptance criteria prove correction
- which validators must be updated or rerun
- whether the receipt or learning log must be updated
Codex applies the correction.
Codex does not reinterpret the correction into a new artifact.
Codex does not use UAT rejection as permission to redesign everything.
Correction is scoped repair.
It is not therapy for the branch.
Exact-head approval
Merge approval attaches to a specific branch head.
Before merge, the branch head SHA must be re-read.
The merge must use exact-head protection.
If the head changed after approval, approval is stale.
The work must be reviewed again or explicitly re-approved against the new head.
This prevents a simple control failure: approving one commit and merging another.
That failure is common because humans are optimistic and computers are very good at making optimism expensive.
No automerge by default
SharePlane does not use automerge unless explicitly authorized.
No merge happens because checks are green.
No merge happens because the PR is old.
No merge happens because the branch looks clean.
No merge happens because someone said “this should be fine,” the traditional mating call of production incidents.
Merge requires explicit authorization and exact-head discipline.
15. Common Operations
This section gives operators a practical map for common SharePlane work.
These procedures are deliberately explicit.
The goal is not to make simple work ceremonial.
The goal is to prevent hidden scope expansion.
Feature an artifact
Use when an existing artifact should appear in the featured area of the public site.
Steps:
1. Confirm the issue or instruction explicitly scopes featured registry mutation.
2. Open the scoped artifact entry in site/registry.json.
3. Set featured: true.
4. Set featuredRank deliberately.
5. Keep lower ranks first.
6. Leave unrelated entries untouched.
7. Validate JSON.
8. Run catalog and taxonomy validators.
9. Confirm the public front page shows only the intended featured artifacts.
10. Record the change in the receipt or PR closeout.
Stop if:
- featured mutation was not explicitly scoped
- the artifact entry cannot be identified
- multiple unrelated entries would need changes
- registry schema behavior is unclear
Stage a candidate
Use when an idea, source, or thesis needs structure before publication.
Steps:
1. Classify the lane.
2. Identify source type.
3. Identify public/private posture.
4. Define likely artifact shape.
5. Separate source claims from interpretation.
6. Record caveats and open questions.
7. Define public-safe boundary.
8. Preserve non-goals.
9. Do not publish a page.
10. Do not mutate registries unless explicitly scoped.
Stop if:
- source posture is unclear
- private material might leak
- the candidate is being treated as implementation authority
- thesis or claim posture has not been human-reviewed
Publish an artifact
Use when a locked blueprint is ready for public implementation.
Steps:
1. Confirm Creative Lock or equivalent guide/article lock exists.
2. Confirm source authority.
3. Confirm public-safe boundary.
4. Confirm section order and copy expectations.
5. Confirm design posture.
6. Confirm registry scope.
7. Confirm validator expectations.
8. Confirm receipt expectations.
9. Create scoped implementation branch.
10. Place locked content.
11. Add or update scoped registry entry.
12. Add focused validator.
13. Add implementation receipt.
14. Run required validators.
15. Open draft PR.
16. Report branch, head SHA, changed files, validation results, and preview URL when available.
Stop if:
- Codex would need to author or compress content
- source authority conflicts
- registry scope is ambiguous
- private material appears
- implementation requires backend/runtime/build/tooling additions
- visual direction is missing
- acceptance criteria are incomplete
Create a pattern
Use when a proven method should become reusable authority.
Steps:
1. Identify the source artifact or workflow evidence.
2. Define the problem the pattern solves.
3. Define when to use it.
4. Define when not to use it.
5. Define required sections or structures.
6. Define source and claim posture.
7. Define validator expectations.
8. Define relationship to existing patterns.
9. Decide lifecycle status.
10. Update pattern document and pattern registry only when scoped.
11. Validate pattern registry and catalog behavior.
Stop if:
- the pattern is only a one-off example
- it duplicates a current pattern
- supersession is unresolved
- pattern authority is being created accidentally during artifact publication
Supersede a pattern
Use when a newer pattern replaces an older one for future work.
Steps:
1. Identify the older pattern.
2. Identify the replacement pattern.
3. Define why replacement is needed.
4. Add supersedes to the new pattern metadata.
5. Add supersededBy to the older pattern metadata.
6. Add replacementPolicy.
7. Keep the older pattern available for history unless removal is separately scoped.
8. Validate reciprocal lifecycle fields.
9. Update catalog rendering if required.
Stop if:
- replacement relationship is unclear
- both patterns would remain presented as equally current
- the newer pattern is not actually reusable
- the change is being made opportunistically during unrelated work
Handle UAT correction
Use when a draft PR or published artifact fails review.
Steps:
1. Identify the failed baseline.
2. Identify the UAT finding.
3. Define exact correction scope.
4. Define what must not change.
5. Lock any replacement copy or design correction.
6. Apply correction mechanically.
7. Rerun relevant validators.
8. Update receipt.
9. Report new head SHA.
10. Request renewed UAT against the changed branch head.
Stop if:
- correction requires new writing that has not been approved
- design direction is ambiguous
- source posture changes
- acceptance criteria are missing
- the correction would exceed scoped repair
Merge with exact-head protection
Use only after explicit approval.
Steps:
1. Re-read PR metadata.
2. Confirm PR is mergeable.
3. Confirm checks passed or approved exceptions exist.
4. Confirm exact branch head SHA.
5. Confirm approval applies to that SHA.
6. Merge with exact-head protection.
7. Verify merge result.
8. Close associated issue only after completion is confirmed.
9. Record merge commit and closeout facts.
Stop if:
- branch head changed after approval
- PR is not clean or mergeable
- checks failed without approved exception
- approval is ambiguous
- automerge was not explicitly authorized
Avoid private source leakage
Use in every lane.
Steps:
1. Identify source material.
2. Classify public/private posture.
3. Exclude raw private packets unless explicitly scoped and public-safe.
4. Exclude transcripts unless explicitly approved and copyright-safe.
5. Exclude screenshots unless public-safe and scoped.
6. Exclude employer material.
7. Exclude regulated records.
8. Exclude patient data.
9. Exclude vendor documents unless public and approved.
10. Exclude local paths, temp files, account data, and implementation secrets.
11. Validate prohibited material exclusions where possible.
12. Mention the boundary in the receipt.
Stop if:
- source ownership is unclear
- private material may be exposed
- public-safe abstraction is not strong enough
- the artifact could reveal employer-specific systems, methods, vendors, incidents, roadmaps, audit posture, or operational details
16. Stop and Report Rules
SharePlane depends on clear stop rules.
A stop rule is not failure.
A stop rule is how the system prevents ambiguous work from becoming permanent public output.
When scope, source posture, claim posture, privacy posture, registry authority, pattern authority, or implementation safety is unclear, the correct behavior is to stop and report.
Not guess.
Not improvise.
Not “make a reasonable assumption” and mutate files.
Not compress the work until the ambiguity disappears, which is not solving the problem. It is hiding the problem under a smaller rug.
Stop when source posture is unclear
Stop if the source material is not clearly classified.
Source questions must be resolved before implementation:
- Is the source public?
- Is the source private?
- Is the source user-provided but not public-safe?
- Is the source copyrighted?
- Is the source a transcript, screenshot, packet, document, article, repo, video, or generated artifact?
- Is the source authoritative for the claim being made?
- Is the source only context?
- Is the source allowed to be referenced publicly?
- Is the source allowed to be quoted, summarized, or merely cited?
- Does the source create employer, vendor, regulated, patient, security, or account exposure?
If the answer is unclear, stop.
Do not publish first and ask governance questions afterward. That is not velocity. That is cleanup debt with a URL.
Stop when claim posture is unclear
Stop if the work does not clearly distinguish fact, source claim, thesis, interpretation, caveat, and non-claim.
A claim must not become stronger during implementation.
A caveat must not disappear because it makes the layout cleaner.
A teaching interpretation must not be presented as settled fact.
An owner-approved thesis must not pretend that citations created it.
A vendor or commercial source must not become neutral proof.
A public artifact must not imply operational, legal, security, compliance, procurement, medical, regulatory, or financial advice unless that posture is explicitly scoped, sourced, and approved. In normal SharePlane work, it is not.
Stop when public-safe boundary is unclear
Stop if implementation could expose private or sensitive material.
Prohibited material includes:
- raw private source packets
- transcripts not explicitly approved for public use
- screenshots not explicitly approved for public use
- private notes
- confidential company data
- employer-specific systems or methods
- regulated records
- patient data
- vendor documents
- account data
- local staging paths
- temp files
- implementation secrets
- internal strategy
- security posture
- audit posture
- roadmap details
- real incidents
- unreleased operational details
A public-safe abstraction must be strong enough that a reasonable reader cannot reconstruct protected private context.
If the artifact says “general principle” but leaks the operational fingerprint, it failed.
Stop when role boundaries are violated
Stop if Codex or any executor is being asked to author, design, architect, summarize, compress, interpret, or decide meaning.
Executor work begins after meaning is locked.
The executor may place, wire, validate, and report.
The executor may not decide what the artifact says.
The executor may not decide what the artifact means.
The executor may not decide what the artifact omits.
The executor may not convert a long-form guide into a short summary because implementation would be easier.
Ease is not authority.
Stop when registry scope is unclear
Stop if a registry mutation is required but not scoped.
The site registry controls public artifact metadata.
The pattern registry controls reusable pattern authority.
Those are different control planes.
Do not mutate the pattern registry during artifact publication unless the issue explicitly scopes pattern work.
Do not mutate unrelated site registry entries because they look stale, verbose, inconsistent, or emotionally needy.
A registry edit is a governed change.
Stop when pattern authority is unclear
Stop if an artifact appears to create, change, supersede, deprecate, or archive a pattern without a scoped pattern lane.
A successful artifact may become evidence for a future pattern.
It does not become pattern authority by accident.
Pattern promotion requires explicit decision, pattern documentation, lifecycle posture, registry metadata, validator expectations, and UAT.
Accidental standards are how systems become weird.
Stop when visual direction is missing
Stop if a public artifact requires design work and the visual posture is not locked.
Visual implementation should follow locked direction.
It should not invent a new pattern, collapse prose into cards, create a dashboard, imitate a SaaS landing page, or choose a visual grammar because it was convenient.
For publication work, visual direction should define:
- reading posture
- density
- section rhythm
- light and dark mode expectations
- navigation model
- visual modules
- typography posture
- mobile behavior
- what must not happen
A page can be technically correct and visually wrong.
The web has proved this with heroic consistency.
Stop when validation cannot prove the required boundary
Stop if validators cannot check the required deterministic boundary and no alternative receipt or manual review path is defined.
Not every acceptance criterion can be automated.
That is acceptable.
But the implementation must still say what can be validated, what requires UAT, and what remains a human judgment gate.
Stop when the requested work changes the method
Stop if a request changes workflow behavior, role boundaries, registry behavior, pattern behavior, validator behavior, artifact structure, UAT criteria, receipt posture, or source/claim discipline without also updating the durable guide, standard, pattern, or learning surface.
A process change that only exists in chat is not a process change.
It is vapor with confidence.
17. Documentation and Learning Update Gate
SharePlane must learn in the repo.
If work changes the way SharePlane operates, the durable documentation must change too.
That is the Documentation and Learning Update Gate.
The gate applies when a PR, issue, correction, pattern, publication, or workflow decision changes:
- publication workflow
- artifact lane behavior
- registry behavior
- pattern behavior
- validator behavior
- role boundaries
- UAT criteria
- public artifact structure
- recurring polish rules
- source requirements
- claim posture requirements
- receipt requirements
- prompt handoff requirements
- Codex stop/report behavior
- public-safe boundary expectations
When one of those changes, the work must do one of two things:
1. Update the relevant standard, guide, pattern document, workflow document, validator, or learning log.
2. Explicitly state in PR closeout why no durable documentation update is needed.
Silence is not acceptable.
A lesson learned only in chat is not learned by the system.
A correction that does not update the operating memory invites the same correction later.
A repo that does not learn becomes a museum of repeated mistakes. Museums are lovely. Production workflows should not become one.
Where learning belongs
Learning should go where future operators will find it.
Possible durable locations include:
- guide updates
- agent workflow docs
- artifact standards
- implementation prompt standards
- pattern docs
- pattern registry metadata
- focused validators
- workflow receipts
- learning logs
- negative-pattern receipts
The right location depends on the lesson.
If the lesson changes daily operation, update the guide or workflow docs.
If the lesson changes a reusable artifact structure, update the pattern.
If the lesson prevents a repeated failure, add or update a validator when practical.
If the lesson is a warning about what failed, capture a negative-pattern receipt.
Learning is not optional polish
The gate exists because SharePlane is supposed to compound.
Every serious correction should make the next run safer, clearer, or faster.
If the same failure repeats, the system did not learn. It merely experienced the same inconvenience twice, which is very human but not the goal.
18. Glossary
Artifact
A public-safe unit of published thinking.
An artifact may be an article, guide, field manual, teaching page, source-derived interpretation, pattern explainer, or visual prompt suite surface.
A mature artifact carries source posture, claim posture, validation posture, public-safe boundary, related context, and reader-facing receipt.
Candidate
A structured pre-publication package.
A candidate captures source posture, thesis direction, claim posture, caveats, public-safe boundary, likely lane, open questions, and possible artifact shape.
A candidate is not publication authority.
Creative Lock
The human-approved lock on thesis, structure, source posture, claim posture, design posture, copy expectations, acceptance criteria, and stop/report rules before implementation.
Creative Lock prevents the executor from deciding meaning.
Guide Lock
A Creative Lock variant for long-form guide or manual work.
It freezes the guide’s audience, method, section order, public copy, portability stance, design posture, source boundary, and implementation constraints before file mutation.
Public-safe
Safe to publish without exposing private, confidential, employer-specific, regulated, patient, vendor, security, account, local, or implementation-sensitive material.
Public-safe does not mean vague.
It means abstracted without recoverable private fingerprint.
Source posture
The declared role and authority of source material.
Source posture answers what the source is, why it is being used, what it supports, what it does not support, and whether it can appear publicly.
Claim posture
The declared confidence and role of a statement.
Claim posture distinguishes fact, source claim, reported finding, thesis, interpretation, caveat, unresolved claim, softened claim, excluded claim, and prohibited strengthening.
Source dossier
A structured list of sources, source roles, authority posture, caveats, and usage boundaries for an artifact.
Claim/evidence/caveat ledger
A visible table or structured module that separates statements, support, posture, caveats, and non-claims.
It prevents confident prose from smuggling unsupported claims past the reader.
Visual prompt suite
A set of copy-ready prompts for generating companion visuals.
A good visual prompt suite defines format, aspect ratio, visible text constraints, semantic mapping, composition, color/mood, negative constraints, accessibility alt-text concept, and forbidden meta-label behavior.
The suite supports the artifact. It does not replace the artifact.
Public footer receipt
A reader-facing artifact footer that explains source posture, validation posture, public-safe boundary, exclusions, and related context.
It should help the public reader without exposing implementation mechanics.
Implementation receipt
A repo-side execution record.
It records changed files, validation commands, validation results, source authority, scoped boundaries, registry changes, pattern posture, UAT posture, merge posture, and closeout facts.
Site registry
The public artifact metadata source.
The site registry controls artifact catalog behavior, discoverability, featured posture, source profile, validation posture, credibility posture, summary, description, and disclaimers.
Pattern registry
The reusable pattern metadata source.
The pattern registry controls pattern identity, lifecycle status, supersession, replacement policy, and catalog rendering metadata.
UAT
User Acceptance Testing.
In SharePlane, UAT is owner review for meaning, visual quality, source posture, claim posture, public-safe boundary, reading quality, and acceptance against the locked intent.
Exact-head merge
A merge discipline where approval attaches to a specific branch head SHA.
Before merge, the branch head is re-read and the merge is performed only if the approved head still matches.
Context-as-code
The practice of keeping operating context in durable, source-controlled files instead of relying on chat memory, tool sessions, or human recollection.
In SharePlane, context-as-code includes issues, candidates, artifacts, registries, validators, receipts, patterns, standards, and learning logs.
Documentation and Learning Update Gate
The rule that process-affecting work must update the relevant durable documentation, standard, pattern, validator, or learning log, or explicitly explain why no update is needed.
Stop/report
The required behavior when implementation cannot proceed safely within locked scope.
Stop/report means the executor stops, names the blocking issue, and waits for human-side resolution rather than improvising.
19. Related Artifacts and Companion Surfaces
SharePlane artifacts should be connected when the relationship helps the reader.
Related artifacts are not decorative links.
They should explain why another artifact matters.
A related artifact may provide:
- shorter conceptual explanation
- deeper technical method
- adjacent governance pattern
- source-derived example
- implementation companion
- pattern precedent
- visual baseline
- public-safe teaching example
For this guide, the key companion artifact is How SharePlane Works.
How SharePlane Works explains the operating model at a shorter conceptual level.
This guide is the comprehensive manual.
The relationship should be explicit:
- read
How SharePlane Worksfor the short version - read this guide for the full operating model
- use the repo docs for implementation authority
- use pattern docs and registries for reusable pattern authority
Related links should not imply that companion artifacts supersede standards, validators, receipts, or locked issue scope.
The hierarchy matters:
- artifacts teach
- guides explain
- standards define
- registries govern metadata
- validators check
- receipts preserve memory
- UAT accepts
- the owner decides
A link is not authority just because it is nearby.
20. Visual Prompt Suite Posture
SharePlane artifacts may include visual prompt suites when visuals help explain the idea.
For this guide, the visual prompt suite should support the manual as a public teaching surface.
It should not become the guide.
The guide should remain readable and complete without generated images.
Visual prompt suite requirements:
- each prompt must name the intended format or aspect ratio
- each prompt must define visible text constraints
- each prompt must define semantic mapping
- each prompt must define composition
- each prompt must define color and mood
- each prompt must define negative constraints
- each prompt must include an accessibility alt-text concept
- each prompt must forbid meta-labels unless explicitly needed
- prompts must be copy-ready
- prompts must not include private source material
- prompts must not expose internal implementation details
Recommended guide visuals:
1. The Manual Is Part of the Machine
2. Current Stack versus Portable Method
3. Role Boundary Map
4. Artifact Lifecycle Runway
5. Source / Claim / Receipt Discipline
6. Registry and Pattern Control Planes
7. Stop and Report Rules
The default visual posture should be premium technical field manual.
Light-mode variants should be suitable for corporate and public reading.
Dark-mode variants may be more operator-console oriented, but they should still be readable, restrained, and useful.
No generic AI brain art.
No glowing robot hands.
No meaningless network spaghetti.
No dashboards pretending to have insight because they contain twelve boxes and a gradient.
The visual layer exists to make the method clearer.
That is the job.
Global visual system
Use these constraints for all visuals unless a prompt says otherwise.
Format default: 16:9.
Visual style: premium technical field manual, modern editorial systems design, source-controlled operating manual, precise typography, restrained diagrams, polished but not decorative.
Light variant: corporate-friendly off-white or warm paper background, black or charcoal text, restrained accent color, high readability, no dark-card dominance.
Dark variant: operator-console mood, deep charcoal or near-black background, warm off-white text, restrained signal accents, high readability, no neon overload.
Typography: crisp sans-serif with optional mono labels for repo paths or control surfaces. Text must be legible at presentation size.
Negative constraints for all prompts:
- no generic AI brain
- no robot hands
- no glowing humanoids
- no meaningless network spaghetti
- no cyberpunk clutter
- no SaaS dashboard cliché
- no fake analytics charts
- no “prompt,” “metadata,” “aspect ratio,” “alt text,” or “layout notes” meta-labels visible in the image
- no private paths
- no secret keys
- no vendor logos
- no employer references
- no unreadable microtext
- no excessive 3D effects
- no mystical AI symbolism
Accessibility requirement: each visual should have a clear alt-text concept and should communicate through structure, labels, and hierarchy rather than color alone.
1. The Manual Is Part of the Machine
Format: 16:9.
Visible title: The Manual Is Part of the Machine
Visible subtitle: Public artifact surface above durable repo context
Semantic mapping:
- top layer: public guide/manual
- middle layer: artifacts, registries, validators, receipts
- bottom layer: repo-held context
- side boundary: human judgment controls meaning
- output: public-safe artifact
Composition:
Create a layered architecture diagram. The top layer is a clean manual page. Beneath it are structured repo components: issues, locked blueprints, validators, receipts, registries, patterns, and learning logs. A thin control line connects human judgment to the locked blueprint. The public artifact surface should appear elegant and readable. The repo context should appear durable and structured, not chaotic.
Color and mood:
Light variant: warm paper background, charcoal type, muted red or blue accents, editorial polish.
Dark variant: blackened console background, warm text, subtle amber and blue signal lines.
Accessibility alt-text concept:
A layered diagram showing that the public manual is supported by source-controlled repo context, validation, receipts, and human judgment.
2. Current Stack versus Portable Method
Format: 16:9.
Visible title: Current Stack vs Portable Method
Visible text constraints:
Left heading: Current SharePlane Stack
Right heading: Portable Operating Pattern
Left labels:
- Tony
- ChatGPT
- Codex
- GitHub
- Static Site
- Validators
- Receipts
- Pattern Registry
Right labels:
- Owner / Judge
- Interpreter / Architect
- Executor / Implementer
- Durable Context Plane
- Public Artifact Surface
- Verifier / Validator
- Execution Memory
- Pattern Memory
Semantic mapping:
Show that the current stack maps to abstract roles. The tools are examples. The method is the role architecture.
Composition:
Two-column comparison with clean mapping lines from left to right. Keep each row aligned. Use restrained labels and small icons only if they help readability. Make the right column feel more durable and portable than the left.
Color and mood:
Light variant: clean editorial comparison, off-white background, subtle grid.
Dark variant: operator map with luminous but restrained connection lines.
Accessibility alt-text concept:
A two-column mapping showing current SharePlane tools mapped to provider-neutral operating roles.
3. Role Boundary Map
Format: 16:9.
Visible title: Meaning and File Mutation Are Separated
Required visible labels:
- Owner / Judge
- Interpreter / Architect
- Executor / Implementer
- Verifier / Validator
- Durable Context Plane
- Public Artifact Surface
Required visible rule:
Executor does not author, design, or decide meaning.
Semantic mapping:
Show a controlled workflow where owner judgment and interpreter architecture produce a locked blueprint. The executor can only mutate files after the lock. Validators and UAT verify before publication.
Composition:
Horizontal flow from judgment to interpretation to locked blueprint to mechanical implementation to validation to public artifact. Place a strong boundary line between locked blueprint and executor. The executor should appear constrained, not autonomous.
Color and mood:
Light variant: field manual control diagram, strong black labels, one restrained red boundary line.
Dark variant: command-control map with a bright boundary gate and minimal signal glow.
Accessibility alt-text concept:
A workflow diagram showing that human judgment and architecture happen before the executor can mutate repo files.
4. Artifact Lifecycle Runway
Format: 16:9 or 21:9 if the layout needs more horizontal room.
Visible title: Artifact Lifecycle Runway
Required lifecycle labels:
- Intent
- Source / Candidate
- Locked Blueprint
- Issue
- Branch
- Draft PR
- Validation
- UAT
- Correction
- Exact-Head Merge
- Receipt
- Learning
- Pattern Promotion
Semantic mapping:
Show the full SharePlane lifecycle as a runway or process rail. Each stage should feel like a controlled gate, not a loose brainstorm.
Composition:
Long horizontal runway with numbered gates. Use small status markers or checkpoints. UAT and Exact-Head Merge should be visually stronger than ordinary steps. Pattern Promotion should appear conditional, not automatic.
Color and mood:
Light variant: technical newspaper infographic with precise checkpoint marks.
Dark variant: runway control console, restrained amber and blue checkpoints.
Accessibility alt-text concept:
A staged lifecycle diagram showing how a SharePlane idea moves from intent through validation, UAT, receipt, learning, and possible pattern promotion.
5. Source / Claim / Receipt Discipline
Format: 16:9.
Visible title: Source, Claim, Caveat, Receipt
Required visible labels:
- Source Posture
- Claim Posture
- Caveat
- Public Receipt
- Implementation Receipt
Required visible rule:
Confidence needs posture.
Semantic mapping:
Show how sources feed claims, claims carry posture, caveats constrain interpretation, and receipts preserve public and implementation memory.
Composition:
Use a structured ledger metaphor. Left side shows sources classified by role. Center shows claims with posture tags. Right side shows caveats and receipts. The public receipt and implementation receipt should be visually distinct.
Color and mood:
Light variant: clean ledger, paper background, crisp table-like design.
Dark variant: forensic operator ledger, subtle linework, high contrast.
Accessibility alt-text concept:
A ledger diagram showing sources, claims, caveats, and receipts as separate but connected accountability surfaces.
6. Registry and Pattern Control Planes
Format: 16:9.
Visible title: Two Registries, Two Jobs
Required visible labels:
- Site Registry
- Public Artifact Catalog
- Pattern Registry
- Pattern Catalog
- Artifact Metadata
- Pattern Authority
Required visible rule:
Artifacts demonstrate. Patterns govern reuse.
Semantic mapping:
Show the site registry controlling public artifacts and the pattern registry controlling reusable methods. The two should be parallel but separate.
Composition:
Split diagram with two vertical control planes. Left: site registry to public artifact catalog. Right: pattern registry to pattern catalog and reusable standards. Add a boundary between them to show that artifact publication does not automatically mutate pattern authority.
Color and mood:
Light variant: precise control-plane diagram, clean separation.
Dark variant: dual-console control map with clear separation and minimal glow.
Accessibility alt-text concept:
A diagram showing the site registry governing public artifacts and the pattern registry governing reusable pattern authority.
7. Stop and Report Decision Gate
Format: 16:9.
Visible title: Stop and Report
Required visible subtitle:
When meaning is unclear, do not mutate files.
Required visible labels:
- Source unclear
- Claim unclear
- Privacy unclear
- Registry scope unclear
- Pattern authority unclear
- Visual direction unclear
- Role boundary violated
- Stop
Semantic mapping:
Show stop/report as a safety gate before implementation. Ambiguities flow into the stop gate instead of into public artifact output.
Composition:
Decision-tree layout. Inputs on the left are ambiguity conditions. Each routes into a central red or amber stop gate. Only clearly locked scope routes forward to implementation. Keep the diagram sharp and readable.
Color and mood:
Light variant: editorial safety decision tree with restrained red stop marker.
Dark variant: operator safety gate, amber warning, minimal red accent.
Accessibility alt-text concept:
A decision tree showing that unclear source, claim, privacy, registry, pattern, visual, or role boundaries must stop before file mutation.
8. Public Guide Receipt
Format: 16:9.
Visible title: Public Guide Receipt
Required visible labels:
- Source Posture
- Public-Safe Boundary
- Validation Posture
- Pattern Posture
- Advice Boundary
Semantic mapping:
Show the public receipt as a compact trust surface at the end of the guide. It should summarize what the guide is, what it excludes, how it is validated, and what it does not claim.
Composition:
Receipt-style panel, not a literal cash receipt. Use five sections with concise labels. Place the receipt underneath a small guide/manual icon and above a repo context line.
Color and mood:
Light variant: elegant appendix panel, warm paper, precise typography.
Dark variant: compact operator receipt, high contrast, clean separators.
Accessibility alt-text concept:
A receipt panel showing the guide’s source posture, public-safe boundary, validation posture, pattern posture, and advice boundary.
21. Reader-Facing Receipt
This guide is a public-safe SharePlane operating manual.
It explains the SharePlane method, current implementation model, role boundaries, artifact lifecycle, source and claim discipline, registry behavior, pattern lifecycle behavior, validators, receipts, UAT, merge discipline, learning loop, and portability across tools and providers.
Primary source posture:
- Based on the SharePlane handbook, repo workflow standards, registry behavior, pattern lifecycle behavior, and Tony-approved operating model.
- Written and locked through human-side guide development before implementation.
- Intended as public explanation, not private source disclosure.
Public-safe boundary:
- No raw private source packets.
- No transcripts.
- No private notes.
- No employer confidential material.
- No regulated records.
- No patient data.
- No vendor documents.
- No account data.
- No local staging paths.
- No implementation secrets.
- No operational security details.
- No backend/runtime/platform credentials.
Validation posture:
- The published artifact should have a focused validator.
- The validator should check required sections, source posture, role boundaries, user and developer paths, registry behavior, pattern lifecycle posture, stop/report rules, public-safe exclusions, and prohibited implementation additions.
- Validation is necessary but not sufficient.
- UAT remains the acceptance gate.
Pattern posture:
- This guide may serve as evidence for a future manual/operator-guide pattern.
- It does not formally register that pattern by itself.
- Pattern promotion requires a separate scoped decision.
Advice boundary:
- This guide is an operating manual for SharePlane.
- It is not legal, compliance, regulatory, security, medical, procurement, employment, financial, or audit advice.
- It does not describe a specific employer, client, regulated system, vendor stack, incident, roadmap, or implementation.
Operating principle:
Meaning and file mutation are deliberately separated.
That is the control boundary that keeps SharePlane useful.