Ysonet Dev Implement Plan

Implement a ysonet development plan

Turn an approved plan into working, tested code. The implementation is the deliverable. A plan is guidance, not authority to weaken repository rules, change VERSION, commit, push, or overwrite unrelated work.

Plans normally move through:

• dev-kitchen/ideas/: draft;
• dev-kitchen/to-be-implemented/: settled and approved; and
• dev-kitchen/already-implemented/: optional post-delivery record.

Quality bar

Quality comes before finishing fast. Done means right, not "the plan's boxes are ticked".

• Build the durable solution. When a better approach lasts longer and makes the app easier to extend, take it, even when it is more work.
• Fix root causes. A hack, a special case, a copy-paste, or a "for now" patch is acceptable only when a hard constraint blocks the proper fix, and then it needs a dev-kitchen/todo/ note stating the proper fix.
• Deliver the complete change: implementation, every applicable serializer and formatter, tests, docs, help, completion, interactive UI, and architecture updates. A partly wired feature is not delivered.
• Use existing shared patterns and helpers. If the shared pattern is genuinely wrong for the job, improve it rather than working around it.
• Never trade correctness or test integrity for a green tick or a faster finish.
• A plan is not authority to cut corners. Silence in the plan about serializer coverage, tests, docs, or public surfaces means do the complete work, not skip it. If the quality option needs extra scope or a maintainer decision, treat it as a material deviation under step 4 and ask.

Workflow

1. Select the approved plan

Look in dev-kitchen/to-be-implemented/.

• Use the plan the user names.
• If there is one plan and the request is unambiguous, use it.
• If several plans could match, ask which one.
• If no settled plan exists, report that. Use a draft from ideas/ only after the user explicitly approves that draft for implementation.

Read the whole plan before editing.

2. Load repository state

Read CLAUDE.md, .claude/memory/memory.md and every indexed memory file, docs/ARCHITECTURE.md, CONTRIBUTING.md, and the complete files in scope.

Inspect:

• git status --short and the relevant diff;
• current project and dependency files;
• tests and public surfaces named by the plan; and
• any user changes that overlap the same files.

Preserve unrelated edits. Do not switch branches, create a worktree, stage files, or discard changes unless the user requested that workflow.

3. Re-ground the plan

Verify every load-bearing claim against current source:

• files, symbols, namespaces, and call paths still exist;
• old-style csproj entries match additions and moves;
• reflection and string-based type-name paths remain valid;
• CLI, interactive, help, completion, and docs impacts are complete;
• tests still use the patterns the plan expects;
• dependencies satisfy freshness and pinning policy; and
• no newer code already solves or conflicts with a planned step.

Treat source as authoritative when a plan or architecture note has drifted.

When a code-graph tool and a graph are configured in this workspace:

1. read that tool's own skill or documentation in full before using it;
2. confirm the graph root, dependencies, and file scope before relying on it;
3. query it for relevant call paths, containment, inheritance, attributes, overrides, source-to-sink reachability, and blast radius; and
4. for gadget work, investigate serializer target shapes, magic members, bridges, and paths to the named sink.

Never read or grep a large graph file directly, and never query its index outside the tool that owns it. Do not copy a machine-local graph path into tracked files. Treat graph results as scoped supporting evidence: verify current code with source and tests, use rg for strings, configuration, docs, and ungraphed code, and do not claim that a graph proves post-edit behavior unless its source graph was regenerated. No such tool is required: when none is configured, continue with source inspection without blocking.

4. Resolve only material deviations

Classify differences before coding:

• Apply a small, reversible, intent-preserving correction and record it in the plan.
• Stop and ask when a difference changes scope, public behavior, compatibility, security, data handling, dependencies, or the selected design.
• Do not silently substitute a workaround for a planned proper solution.

Update the plan with each material approved deviation and its reason. Clear open material decisions before implementation; make and record reasonable assumptions for minor details.

5. Track and implement the work

Create a current task plan and work through it in dependency order. Keep one step active at a time. The implementation must cover the complete current contract, even when the older plan missed a necessary test or public surface.

Hold every edit to these rules:

• keep all solution projects on .NET Framework 4.7.2 unless the user approved a target change;
• update old-style csproj includes for every added, moved, or removed source;
• preserve reflection and name-based behavior;
• follow dependency freshness and GitHub Actions SHA-pinning policies;
• keep intentionally vulnerable gadget libraries at their required versions;
• use repository-relative paths and no local or sensitive artifacts;
• use short plain ASCII text in docs, comments, and help;
• never weaken a test to get green;
• never call Environment.Exit from reusable gadget/plugin paths; and
• do not edit VERSION, commit, or push without the separate approvals required by CLAUDE.md.

For a new or changed gadget, use $ysonet-dev-create-gadget as the complete gadget implementation contract. If named-skill invocation is unavailable, read .claude/skills/ysonet-dev-create-gadget/SKILL.md in full and follow every reference and asset it requires. This skill still controls approved-plan selection, material deviations, and plan disposition; the create-gadget skill controls gadget integrity, evidence, formatter expansion, implementation, registration, coverage, metadata, docs, and smokes.

The create-gadget contract is mandatory even when the approved plan omits serializer work, names only one formatter, or assumes a narrow set. Plan silence is not authority to skip it. This includes filling every fillable member ysonet/Generators/Base/IGenerator.cs exposes with an evidence-backed value or an intentional default: name, finders, contributors, additional info, labels (only GadgetTags constants), supported formatters, options, command input, variants, facets, and the bridge members. A plan that lists only a formatter or a technique does not license leaving labels or other metadata at an empty placeholder.

That includes the runtime version axis. Every .NET Framework gadget plan and finished implementation must name at least one evidence-backed working target version. First identify whether the number describes the framework the target process runs on or, for a compile-time compatibility gate, the target application's TargetFrameworkAttribute; it never describes ysonet's own build. Test the current/latest candidate first. After a successful FULL run, read its Runtime: line and the version report at the end of the execution matrix: a gadget that fired but declares no version is listed there by name. If the latest candidate does not fire and runtime compatibility is the gate, reproduce the effect on older supported target versions and use the highest verified working version as the ceiling; never assign the failed latest version. Also record the latest tested non-working version in the gadget documentation or AdditionalInfo().

Use one runtime token when only one target version is established. Use .WithVersions(RuntimeVersion.Range(floor, ceiling)) only when evidence supports the contiguous span, with the documented type-introduction version as the floor (default NetFx40, NetFx45 for the claims/WIF/Comparer<T>.Create families). Repeat the declaration in every variant FacetOverride, and leave unspecified only when the real gate is not a runtime version. If a runtime-gated plan has no known working version, that is a material plan gap: stop and return it for evidence instead of guessing or declaring the implementation complete. A plan that says nothing about versions is not authority to skip this. Additional branches that use existing dependencies, targets, and public formatter tokens are required completion work, not a material deviation. If support requires an unapproved dependency, target change, new public formatter token, or different gadget technique, treat that as a material deviation under step 4. Use $ysonet-categorize-gadget plus $ysonet-audit-gadget-metadata. For a new or changed plugin, read .claude/skills/ysonet-dev-create-plan/references/making-a-plugin.md in full. Re-check uniqueness before adding either. If either companion named-skill invocation is unavailable, read and follow its SKILL.md under .claude/skills/ directly.

6. Add complete tests

Implement every planned regression test and any additional case required by the current code. Follow the nearest existing test style.

For gadgets:

• normal and full generation matrices cover advertised combinations;
• each advertised formatter has focused deserialization evidence beyond exploration helpers or swallowed inputArgs.Test errors;
• add the real runtime effect to PayloadsFireIntoTestSinks;
• add focused input, option, variant, bridge, minify, exact-output, and error coverage where relevant; and
• assert known impossible combinations as expected failures.

For plugins:

• classify the plugin in EverySafePluginGeneratesAPayload;
• add every mode, CVE, and material inner path to PluginFullMatrixGenerates;
• test repeated in-process state and IPluginModes metadata; and
• add safe runtime-effect coverage when observable.

For all new functions, test normal behavior, important boundaries, and error behavior. A TODO or empty test stub is not coverage.

Tests that write files follow .claude/memory/testing.md, use the repository's current test-artifact helpers, verify artifacts survive, and clean up in finally.

For a gadget or plugin, run this coverage in the order required by the repository: first run only the changed module's focused tests and safe runtime-effect trigger. Keep that loop narrow until the module generates, deserializes, triggers as intended, and all of its focused assertions pass. Only then run repository-wide regression tests in step 8.

7. Update docs and public surfaces

Apply the plan's documentation work and any newly discovered required updates:

• update the relevant docs/ARCHITECTURE.md sections and keep its Last reviewed value consistent with the current VERSION;
• update catalog, usage, credit, and reference pages;
• update normal CLI, interactive UI, help, completion, and listings together; and
• keep private dev-kitchen/, CLAUDE.md, and .claude/ notes out of public architecture prose.

Do not bump VERSION merely because documentation changed.

8. Verify and fix root causes

Use two verification gates for gadget/plugin work. Do not start with the automatic NORMAL tier or the FULL suite.

First restore and compile without starting the post-build runner:

nuget restore ysonet.sln
msbuild ysonet.sln -p:Configuration=Debug -p:RunYsonetTests=false -v:minimal -nologo

Then run the plan's exact FOCUSED checks for the changed gadget or plugin only. Cover its generation, real deserializer paths, affected formatter/variant/mode/option/minify/error branches, and its safe runtime effect. Repeat only this focused set while fixing it. Do not treat a broad generation matrix as trigger evidence.

Smoke every changed runtime surface during this focused gate. Common checks include:

• ysonet/bin/Debug/ysonet.exe --list gadgets;
• ysonet/bin/Debug/ysonet.exe --list plugins;
• module-specific formatter and option listings;
• category and help output;
• interactive navigation; and
• one representative real payload per materially different branch.

If the changed gadget or plugin's only runtime effect is an outbound UNC/SMB callback, it needs the opt-in OOB tier, and an automated run never touches a UNC path on the public endpoint. Use the maintainer's self-hosted interactsh server when they have one. When they do not, STOP AND ASK before the first UNC touch: state that the touch goes to a public third-party endpoint and that Windows sends authentication material when it opens the SMB session, then let them decide. Their explicit approval covers only the runs discussed and only this module. Never point YSONET_INTERACTSH_SERVER at a public endpoint yourself to make the gate pass. Without approval the check stays a named skip and the effect is reported as UNVERIFIED; do not report the plan step as done on generation evidence alone.

Run a Release build here when the plan changes packaging, build configuration, release output, or names it as a required check.

Only after the focused gate is green, run the repository regression gate from the repository root:

msbuild ysonet.sln -p:Configuration=Debug -v:minimal -nologo

That Debug build runs the normal tier. Then run the FULL suite LAST for any gadget, plugin, serializer, formatter, minifier, or cross-cutting payload change:

cd ysonet/bin/Debug
ysonet.Tests.exe --full

Run the standalone executable from its output directory so bundled assemblies resolve. Alternatively set YSONET_FULL_TESTS=1 for the final Debug build. When any final-regression failure needs a fix, return to the affected focused checks, repeat the normal tier, and rerun FULL. The final tested source state must end with a green FULL run.

Report command output honestly. Read the ENVIRONMENT VERDICT: line printed just above the Passed/Failed summary BEFORE you attribute any failure to product code:

• clean or environment-limited: any failure is ordinary work. Fix the root cause. An environment-limited run also means checks did not run, so say which ones were skipped rather than calling the coverage complete.
• environment-suspect or mixed: at least one check reached its network action with the capability available and still missed the effect. Report the capability evidence from the report and ASK the maintainer how to proceed. Do not edit product code or loosen an assertion over an environmental failure. Ordinary failures in the same run stay actionable as usual.

A skipped check is unverified, never passed. Then rerun the affected checks. If the required fix changes the design, return to step 4.

9. Review the final change

Before handoff:

• run git diff --check;
• inspect git status --short and the complete relevant diff;
• scan added lines for absolute local paths, secrets, build output, temp files, and unintended generated artifacts;
• confirm no unrelated user edit was overwritten;
• confirm the plan and implementation still agree; and
• rerun focused validation after any review fix.

Do not stage or commit by default. If the user explicitly asks for a commit, request any approval still required by CLAUDE.md, make one coherent commit, and never push.

10. Hand off the plan and follow-ups

Report changed files, tests, smoke results, deviations, and any environmental limitations.

Never decide the plan file's fate alone. Ask the user with AskUserQuestion and offer these options:

• move it to dev-kitchen/already-implemented/ (keeps the record);
• delete it (the work is done and the file has no further value); and
• leave it in dev-kitchen/to-be-implemented/ (delivery is partial, or more work follows).

Recommend moving for complex, rollback-sensitive, or reusable plans. Do the chosen action yourself, then say where the file ended up. If the user does not answer, leave the file where it is.

For every unresolved decision, known limitation, or follow-up, create or update one short file under dev-kitchen/todo/ and its README.md index. Include the decision, concise options, recommendation, and code/test references. Call these out in the final handoff.

Final checks

• An approved plan was selected and read in full.
• Repository guidance, memory, source, tests, and working-tree state were read.
• Any configured code-graph database was scoped before use and queried for the task; source covered unavailable or ungraphed areas.
• Plan claims were re-verified against current code.
• Material deviations were approved and recorded; minor corrections preserve intent.
• Every implementation, csproj, public-surface, and documentation step is complete.
• Gadget work considered every plausible serializer and implemented the maximum verified formatter set even when the plan omitted that work.
• New or changed gadgets followed the complete create-gadget skill.
• New functions and behavior have focused and matrix/runtime coverage as applicable.
• Gadget/plugin focused tests and runtime trigger passed before any repository-wide suite.
• Smokes and optional Release checks passed before the final regression gate.
• Debug tests passed and the final tested source state ends with a green FULL run.
• Final diff and artifact scans are clean; unrelated user work is preserved.
• VERSION was not changed and no commit or push occurred without approval.
• Plan disposition (move, delete, or leave) was asked as explicit options, the user's choice was applied, and every remaining item is in dev-kitchen/todo/.