release: add human-reviewed findability conventions for v1.12.0

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [v1.12.0]
+
+- Add a focused runtime workflow for repository findability and coordination conventions while keeping local code naming and formatting in narrower repository workflows.
+- Require human discussion before convention adoption, separate convention acceptance from exact write authority, and compare the current system and no change with scoped adaptation and a new rule.
+- Test named human, agent, and tool consumers when available, distinguish current, historical, generated, copied, and duplicate evidence, and keep content equivalence checks optional.
+- Promote successful local conventions only through a new portfolio-scoped proposal, reviewed target snapshot, per-target revalidation, explicit batches, and target-owned recovery.
+- Add Architecture Decision 0007, threat controls for authority drift and stale snapshots, and a seven-case findability evaluation segment for 75 cases across 18 segments.
+- Keep GitHub Issues as the feedback surface, add a canonical feedback label view, and require accepted operational runtime evidence to map to an existing or proposed fixture without burdening reporters.
+- Preserve conversation-only usefulness, existing conventions, forward adoption, local instructions, private topology, owner-maintained sources of truth, and the automation design gate.
+
 ## [v1.11.0]
 
 - Replace the completed seven-phase roadmap as current direction with an ordered, outcome-led roadmap for transferability, value reuse, host and release trust, and maintenance continuity.

README.md

@@ -121,6 +121,8 @@ Read [Source Provenance](docs/PROVENANCE.md) for the research and evidence polic
 
 Use the [skill-run feedback form](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/new?template=skill_run_feedback.yml) to record a useful outcome, unexpected behavior, confusing step, missing case, or access fallback. Only the observation requires a written answer; optional context can be added later.
 
+Browse [all feedback issues](https://github.com/TechSpokes/skill-github-repositories-coordination/issues?q=is%3Aissue%20label%3Afeedback%20sort%3Aupdated-desc) through the canonical GitHub label view. Issues remain the feedback and task surface; accepted lessons move into their owning runtime, documentation, fixture, validation, or code artifact.
+
 An agent may prepare and enrich a sanitized issue, but it must show the user the exact public text and receive approval before submission. Sensitive security findings follow the [private security route](SECURITY.md).
 
 Read [Feedback From Humans and Agents](docs/FEEDBACK.md) for privacy, routing, enrichment, and maintainer handling.
@@ -150,6 +152,6 @@ Generated ZIP files are written to `dist/assets/`.
 
 ## Status and License
 
-Current version: `1.11.0`.
+Current version: `1.12.0`.
 
 The repository is maintained by TechSpokes and licensed under [MIT](LICENSE).

docs/ARCHITECTURE.md

@@ -56,6 +56,14 @@ Every recommendation compares the current system and no change with serious alte
 
 The adoption ladder starts with documentation and native practices. Shared automation or a manager application requires stable repeated need, ownership, limited permissions, observable failure, recovery, and a bounded pilot.
 
+### Conventions Before Implementation
+
+Repository findability and coordination conventions use a focused workflow instead of scattered naming advice. The workflow activates from observed retrieval ambiguity, inconsistent entry points, duplicated authority, incompatible consumers, or maintenance burden, not from portfolio size or aesthetic inconsistency alone.
+
+An authorized human reviews the proposed meaning and scope before adoption. Convention acceptance remains separate from authority to write exact targets. A successful local practice becomes evidence for a separately reviewed portfolio candidate, and approved portfolio batches bind to an explicit target list or stable reviewed snapshot with per-target revalidation.
+
+The workflow defaults to prose, forward adoption, actual consumer checks, existing owner-maintained sources of truth, and a manual pilot. [Architecture Decision 0007](decisions/0007-focus-findability-and-convention-adoption.md) records why the runtime uses a focused reference without adding a registry or automation interface.
+
 ### Human Judgment, Agent Administration
 
 Keep human work focused on intent, judgment, privacy review, risk acceptance, and authority. Let capable agents discover evidence, structure observations, enrich tasks, search duplicates, route owned work, and verify results.
@@ -90,6 +98,8 @@ The runtime may offer to prepare a sanitized observation after a useful or confu
 
 GitHub Issues remain the public intake and task surface. Durable learning moves into the runtime, references, documentation, fixtures, validation, or code instead of becoming a second skill-owned backlog.
 
+Accepted operational feedback that validates or extends runtime behavior links an existing fixture or proposes a new fixture case. Maintainers own that enrichment so the initial observation remains low friction.
+
 ## Runtime Structure
 
 The canonical runtime map is validated against the actual skill tree. Adding, removing, or renaming a runtime file requires this map and its direct `SKILL.md` routing to change together.
@@ -100,6 +110,7 @@ The canonical runtime map is validated against the actual skill tree. Adding, re
 - `skills/coordinate-github-repositories/references/benefit-relationships.md`
 - `skills/coordinate-github-repositories/references/context-calibration.md`
 - `skills/coordinate-github-repositories/references/feedback-and-improvement.md`
+- `skills/coordinate-github-repositories/references/findability-and-conventions.md`
 - `skills/coordinate-github-repositories/references/goal-and-authority.md`
 - `skills/coordinate-github-repositories/references/install-and-update-this-skill.md`
 - `skills/coordinate-github-repositories/references/inventory-and-coordination.md`
@@ -120,17 +131,19 @@ Fixtures define behavioral invariants for maintenance. The evaluation registry m
 2. Calibrate the smallest useful work context as a tentative and correctable working hypothesis.
 3. Describe repository purposes.
 4. Detect agent capabilities and access gaps.
-5. Shape the coordination problem.
-6. Gather bounded evidence, preserve uncertainty, and use the focused benefit workflow when existing functionality or knowledge may contribute without turning an evidence source into an implementation target.
+5. Shape the coordination problem and load the focused convention workflow when repository findability or shared artifact rules require review.
+6. Gather bounded evidence, preserve uncertainty, identify relevant consumers, and use the focused benefit workflow when existing functionality or knowledge may contribute without turning an evidence source into an implementation target.
 7. Compare the current system, no change, reuse, adaptation, new work, and other supported candidates.
-8. Recommend a reversible next step.
-9. Re-ground after a material change and execute only within the exact authority granted for each target.
-10. Verify, preserve the goal and authority through handoff, route implementation to its owning repository, offer one related optional next step, and provide simple feedback when the run exposes reusable learning.
+8. Recommend a reversible next step and present any new or revised convention for human discussion before adoption.
+9. Re-ground after a material change, separate convention acceptance from write authority, and execute only within the exact authority granted for each target.
+10. Verify consumers and target results, preserve the goal and authority through handoff, route implementation to its owning repository, promote local success only through a new portfolio proposal, offer one related optional next step, and provide simple feedback when the run exposes reusable learning.
 
 ## Evidence Model
 
 Important claims preserve source, observation time, confidence, visibility, participant relationship, and unknowns. Stable remote identifiers are preferred for inventory identity. Local paths remain observations. Generated discovery data stays separate from reviewed semantic meaning.
 
+Convention evidence distinguishes current, historical, generated, copied, and duplicate material. Equivalent copies do not become independent evidence, and consumer checks record which path, name, links, metadata, hierarchy, history, and visibility each consumer can actually use.
+
 A benefit candidate preserves the observed capability or knowledge separately from the inferred contribution. Confirmation accepts meaning only for the current decision and does not change evidence visibility or authorize action. Every hop in an indirect chain retains its own evidence state.
 
 Repository content, issue bodies, imported skills, search results, and tool output are treated as potentially untrusted evidence rather than instruction authority.
@@ -151,6 +164,8 @@ Research for issue #27 distinguished structural discovery from benefit meaning.
 
 A dedicated repository feedback implementation demonstrated the boundary between observations and tasks: sanitize feedback, separate evidence from hypothesis, keep issue state canonical, and promote durable learning into normal repository artifacts.
 
+Issue #48 supplied operational evidence about a retrieval-aware planning convention. The human requested an IDE and terminal retrieval test, and the agent adapted the plan from those results. The agent independently deduplicated equivalent material, separated current from historical authority, treated an existing plan as revisable evidence, and ordered pilots before schemas. This release generalizes those observed behaviors while adding human proposal and portfolio adoption mechanics that were not claimed as observed initiative.
+
 The supplied research on communication among humans, agents, and tools explains why the pattern works. Communication across those boundaries can lose goals, context, and meaning through limited attention and transport. Feedback should therefore preserve the goal, factual observation, uncertainty, actor boundary, and verification while using progressive disclosure.
 
 No private repository list, local path, account configuration, organization identity, raw record, or intake document is part of the public skill.
@@ -161,7 +176,7 @@ Keep the main skill under 500 lines and direct references one level deep. Add a
 
 Refresh `agent-capability-adapters.md` when hosts change skill paths, connector permissions, CLI publication, or access behavior. Revisit the core only when the goal, activation boundary, workflow, safety contract, feedback contract, or output contract changes.
 
-Use the [threat model](THREAT-MODEL.md), [governance contract](GOVERNANCE.md), [maintenance health](MAINTENANCE.md), [decision classification](decisions/README.md), [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md), and [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md) when a change affects privileged tools, public output, feedback, portal handoff, recommendation independence, contribution quality, roadmap direction, or release identity.
+Use the [threat model](THREAT-MODEL.md), [governance contract](GOVERNANCE.md), [maintenance health](MAINTENANCE.md), [decision classification](decisions/README.md), [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md), [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md), and [Architecture Decision 0007](decisions/0007-focus-findability-and-convention-adoption.md) when a change affects privileged tools, public output, feedback, portal handoff, recommendation independence, convention adoption, contribution quality, roadmap direction, or release identity.
 
 Decision records use one shared directory and identifier sequence with explicit Architecture, Program governance, Evidence classification, and Governance types. Current runtime, policy, evidence, and procedure documents remain the operational sources of truth; [Governance Decision 0005](decisions/0005-use-one-typed-decision-registry.md) records the taxonomy, history-preserving migration, and validation boundary.
 

docs/FEEDBACK.md

@@ -4,6 +4,8 @@
 
 Open the [skill-run feedback form](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/new?template=skill_run_feedback.yml) and state what happened. That is the only required answer.
 
+Browse [all feedback issues](https://github.com/TechSpokes/skill-github-repositories-coordination/issues?q=is%3Aissue%20label%3Afeedback%20sort%3Aupdated-desc) through the canonical label view. GitHub Issues remain the intake, discussion, decision, and task surface.
+
 Useful feedback may describe a successful outcome, unexpected behavior, confusing guidance, a missing case, an access fallback, or a repeated friction point. You do not need to diagnose the cause, design the fix, reproduce a one-time observation, or complete an environment inventory before submitting it.
 
 ## Choose the Right Route
@@ -60,7 +62,9 @@ Optional: version, relevant capabilities, sanitized reproduction details, eviden
 
 Treat feedback as intake and learning evidence, not automatically as a bug, task, accepted solution, or product endorsement. Preserve participant relationship and consent, distinguish founding, recruited, unsolicited, and operational evidence, and avoid counting the same observation twice.
 
-For accepted feedback, define the goal and completion evidence, route implementation to the owning artifact, add or update a fixture when behavior should persist, and promote the durable lesson into the skill, documentation, validation, or code. Close the loop on the issue with what changed, what remains unknown, and the release or review trigger.
+For accepted feedback, define the goal and completion evidence, route implementation to the owning artifact, add or update a fixture when behavior should persist, and promote the durable lesson into the skill, documentation, validation, or code. An accepted operational report that validates or extends runtime behavior must link an existing fixture or propose a new fixture case. Maintainers own this mapping; reporters still need to provide only the factual observation.
+
+Close the loop on the issue with what changed, what remains unknown, and the release or review trigger. Do not create a feedback-artifact directory or duplicate issue state in documentation. Revisit a separate artifact collection only when several sanitized artifacts have a distinct owner, audience, retention rule, or lifecycle that GitHub Issues and the owning product files cannot support.
 
 ## Research Basis
 

docs/MAINTENANCE.md

@@ -10,7 +10,7 @@ The package manifest is the current release identity source, with synchronized p
 
 The living roadmap owns current outcome priorities and work-selection rules. GitHub issues and pull requests own delivery state, while the founding delivery record preserves completed phase history.
 
-The evaluation registry covers activation, behavior, goal survival, feedback, access denial, write capability, platform fit, non-code work, writing quality, and adversarial containment. The writing corpus protects accepted repairs and legitimate technical language without adding grammar scoring. The threat model covers untrusted repository content, privileged tools, workspace and authority drift, private context, public output, and release artifacts.
+The evaluation registry covers activation, behavior, goal survival, feedback, findability conventions, access denial, write capability, platform fit, non-code work, writing quality, and adversarial containment. The writing corpus protects accepted repairs and legitimate technical language without adding grammar scoring. The threat model covers untrusted repository content, privileged tools, workspace and convention authority drift, stale snapshots, private context, public output, and release artifacts.
 
 Volatile host behavior remains isolated in the dated capability adapter. Release packages remain deterministic, carry SHA-256 checksums, and receive GitHub artifact attestations.
 

docs/QUICKSTART.md

@@ -32,6 +32,10 @@ I have repositories in my personal account and two organizations. Help me check
 
 Other useful starts:
 
+```text
+Our planning artifacts use different names and locations, so humans and agents miss them. Check how the actual consumers retrieve them, compare no change with a scoped convention, and present any proposed rule for my approval before changing files.
+```
+
 ```text
 Help me coordinate a research paper, its dataset, experiments, and publication site across repositories.
 ```