Structured Coding 0.1.3

Four PRs since 0.1.2, all from real usage feedback rather than anticipated need, closing #25, #26 and #27.

Planning documents stay local by default (#28)

Plans are development artifacts. Two recommended lines, stated where a reader is deciding:

.structured-coding/plans/
.structured-coding/standards.local.md

.structured-coding/standards.md is the deliberate exception and belongs in version control, because whether Git tracks it is exactly what standards.py reads to decide whether a declared command needs approval. Ignoring the whole directory would break team sharing and silently drop that approval requirement.

Sessions are routed through the entrypoint (#29)

• SKILL.md rule 5 now covers a session that is new, replacing another, or a delegated agent — stated as a session boundary, not a per-turn reread.
• The phase table is stated to be the required resource list, so no one reconstructs one from whichever prompt names a kickoff message mentions.
• Before claiming that work does or does not comply with this workflow, the rule being cited must be read in that session.
• The continuity preset names the installed SKILL.md by absolute path at session start, in both the unbound and recovery messages. A missing file omits the sentence rather than printing an unopenable path.
• verify_skill treats SKILL.md, agent-workflow.md and adaptation.md as part of a complete installation.
• All three copyable kickoff messages read the entrypoint first, so a project with no hooks installed still hands the agent the route.

Endpoint authority is explicit and sourced (#25, second incident)

The contract gains ENDPOINT AUTHORITY: implementation and local validation, semantic commits, branch push, PR creation and update, CI repair to review readiness, and merge as separate decisions, each with its shipped default, the section it comes from, and a recorded source — an explicit operator instruction, a repository restriction, or unresolved. Caution is not a source.

A more restrictive contract now overrides the generic defaults only when the restriction records a source. This closes the path by which an agent's own caution was written into a contract, treated as winning over the commit and PR-completion policies, and then inherited by later sessions as though the operator had set it. Merge authority is never widened, in any direction.

Plan the whole route; name who propagates (#26, #27)

• An overall must enumerate every currently identifiable necessary high-level step before the operator accepts it or the first PR is frozen, with each operator requirement matched to a step or to an explicit unresolved decision. It is a completeness check on the route, not a demand for speculative architecture or a minimum step count.
• A merged PR completes that PR. It does not complete its overall, which stays open until every enumerated step is delivered or explicitly dropped. A frozen, bounded PR stays bounded.
• Post-merge backward propagation has a named owner: the implementation session owns the PR record and merge identity; the contract's POST-MERGE SYNCHRONIZATION OWNER — by default the planning session — owns the step and overall updates. Only the owner writes the parent documents, newer content is reconciled rather than overwritten, and owning propagation is not merge authority.

Runtime surface

Behaviour changes in exactly two places, both from #29: the continuity preset's SessionStart message content, and what verify_skill requires. Everything else is specification and documentation. Nothing new blocks anything.

Validation

Ran 171 tests ... OK (skipped=1). All five --check validations PASS. Packages rebuilt: codex 23 files, claude-code 22 files, directory and zip matching shared source.

Open debts, stated rather than hidden

• Continuity compact validation still requires an interactive session; no non-interactive trigger exists, and it is not claimed as passed.
• PostToolUse delivery under an authenticated turn is registered, parsed and budgeted, but not directly observed.
• merge-guard is decided against, not pending. A guard that blocks would take away something a user can do today; anything in this repository stays bypassable by its user.
• No mechanical enforcement is claimed for any specification change in this release. Reading a rule proves nothing about whether an agent followed it.

Structured Coding 0.1.2

Documentation release. Planning documents get a default home.

Changed

The workflow named docs/plan/… and before_end_memory.md as examples and said plainly they were not prescribed. That left every project to invent a location, and put a handoff file at the repository root — the least welcome place to leave one in someone else's project.

Planning documents now default to .structured-coding/plans/<effort>/, one directory per effort:

.structured-coding/plans/infra-exp-p0/overall.md
.structured-coding/plans/infra-exp-p0/step-01-user-map.md
.structured-coding/plans/infra-exp-p0/pr-01a-proposer.md
.structured-coding/plans/infra-exp-p0/pr-01a-contract.md
.structured-coding/plans/infra-exp-p0/handoff.md

That directory already existed for the standards configuration, so the toolkit now has one home in a project rather than two, and your own docs/ tree is left alone. Grouping by effort keeps concurrent overall/step/PR hierarchies from colliding.

It is a default, not a requirement

If you already keep planning documents somewhere else, keep them there. What matters is that one location is the authority and a later session can find it. Nothing refuses to work because of where a document sits.

Commit them if later sessions or teammates need to read them, which is usually the point of writing them down.

Upgrading

Nothing to migrate. Existing plans keep working wherever they are. --check-hooks reports the installed release, now 0.1.2.

Unchanged

SKILL.md and the three preserved prompts are untouched. merge-guard is still not implemented and will not be, and the continuity compact validation debt is still open — see the 0.1.0 notes for what this toolkit deliberately does not do.

Structured Coding 0.1.1

Patch release. One user-facing fix.

Fixed

--check-hooks reported a healthy registration on a Codex project that had never been trusted, while Codex was loading zero hooks — a silent failure where you wait for a hook that will never fire.

It now says so, and names the file to add the entry to:

… Codex has not been told to trust /path/to/project: add a
[projects."/path/to/project"] entry with trust_level to ~/.codex/config.toml,
or trust it through the host. Until then it loads no project-local hooks at all.

It reports and changes nothing: no trust is granted, no configuration is written, nothing is blocked.

Claude Code has no equivalent level and is never shown this.

Also since 0.1.0

PostToolUse delivery, listed as unverified in the 0.1.0 notes, has been observed on Claude Code with a real agent-run git commit reaching the handler. No code changed for that; only what was known about it.

Upgrading

There is no automatic upgrade. Compare or back up an existing installation, then reinstall; --check-hooks reports the installed release. An existing hook registration keeps working and is rewritten only by --upgrade-registration.

Still not implemented, deliberately

merge-guard is not implemented and will not be. A guard that actually blocks would take away something you can do today, and a guard you can work around is a reminder — which the prompts already provide. Everything in this toolkit should stay something you can bypass.

The continuity compact validation debt remains open: triggering compact needs an interactive session, and manufacturing a substitute path would produce evidence about the substitute rather than about compact.

Full 0.1.0 notes, including what this toolkit deliberately does not do: https://github.com/yuema137/structured-coding/releases/tag/v0.1.0

Structured Coding 0.1.0

A workflow for agent coding: agree on the change, let the agent build it, bring the result back into the plan.

This release ships instructions, specifications, and recommended hooks. It reports; it does not enforce. Where a check is not enforced, the documentation says so rather than implying otherwise.

Install

git clone --depth 1 https://github.com/yuema137/structured-coding.git
./structured-coding/scripts/install codex        --project /path/to/your-project
./structured-coding/scripts/install claude-code  --project /path/to/your-project

Then invoke $structured-coding in Codex or /structured-coding in Claude Code. The default installation registers no hooks.

Read the README first — it opens with who this is not for.

What is in it

• The workflow: overall → step → PR planning, a frozen design and execution contract, autonomous implementation, and a backward update after merge.
• The preserved prompts: PR design requirements, implementation working rules, and TEST / CI / GATE rules, deliberately kept whole.
• Three optional hook presets, none registered by default:
  • continuity — compact freshness checks, rescue snapshots, recovery instructions
  • checkpoints — commit-preparation advice and a single non-continuing review notice
  • standards — runs a project's declared checks after a direct git commit and reports
• Project standards configuration: one tracked file declares codebase-wide review conventions and deterministic checks; a developer may add stricter ones locally but never relax the team's.
• Registrations contain no machine-specific path, so one committed to a shared settings file works for a teammate.
• English is authoritative; Chinese mirrors are synchronized.

What it deliberately does not do

• No merge guard. H3 of the hook contract is unimplemented. A merge boundary needs a trusted operator-approval source, and neither a writable field nor a CLI regex is one.
• No enforcement of design freeze, and no mutation guard.
• trigger: "pr" has no hook. Neither host has a PR-completed event, and Stop — the nearest moment — fires at the end of every agent turn, which is not what pr means. That granularity stays an explicit command.
• approve records an operator decision; it does not enforce who made it. Nothing prevents an agent from running it, exactly as nothing prevents an agent from running the installer.

Known limitations

• PostToolUse delivery has not been directly observed under an authenticated turn. Corrected after release: it has since been observed on Claude Code, with a real agent-run git commit reaching the handler. The code in this release is unchanged; only what was known about it is.
• The continuity compact validation debt from the first preset release is still open: model-backed manual and automatic compact, and native rescue evidence, have not been exercised end to end.
• --check-hooks in this release reports a healthy registration even when Codex has not been told to trust the project, in which case it loads no hooks at all. A later release says so; here, check /hooks yourself.
• Codex requires trust at two levels — project trust in CODEX_HOME/config.toml, then per-hook trust by content hash. A -c override does not satisfy the first, and hooks then never load, silently.

Requirements

Python 3.9+, Git, macOS/Linux/WSL. Codex 0.153.4+ or Claude Code 2.1.261+ for the optional hooks. No third-party dependencies.

Installed copies carry VERSION, and --check-hooks reports it.