Proposed Repository Responsibility Overlay And Deferred Migration Notes

• Classification: LOCAL UNCOMMITTED USER-APPROVED P1-002 REPOSITORY PLAN
• Authority: approved target, move-map, mapping-reference and staged-wave input to docs/DESIGN.md; Roadmap remains the sole activation/status owner
• Task: P1-002
• Artifact owner: P1-002 working result; target repository boundary integrates into docs/DESIGN.md, while folder-admission/review mechanics integrate into docs/DEVELOPMENT.md and Project Operations
• Audience: user, Product/Architecture reviewers, developers and AI agents
• Remote source basis: origin/qa@cd26f23f45c2f6378963fb574cccf98807fb7b3c, remote Reset Revision 10
• Local decision basis: user-approved uncommitted Reset Revision 27
• Runtime/tree inventory basis: through origin/qa@cd26f23f4; ca34ce649 added 13 root Node tests and changed bounded Runtime/UI/test files without changing the target, move map, reference mapping or staged-wave decision
• Environment: current Mac checkout, Cloud/Local read-only source and filesystem inspection
• Downstream consumers: P5 module/repository standardization, P7 frontend boundaries, P8 document moves and P9 repeatability
• Proposed: 2026-07-30
• Runtime/DB/provider/service/Production mutation: none
• Retention/removal: retain approved move/reference/wave provenance until downstream owners absorb it and every deferred physical-move consumer and rollback condition is resolved; then remove only by separate disposition

1. Proposed result

The smallest target that satisfies the Reset is a responsibility overlay on the current tree. It keeps the existing top-level paths, loader depths, direct HTTP paths and package boundaries. It narrows what may be added to each path and defers physical moves until a bounded module or consumer has current proof.

This proposal deliberately does not create app/modules, app/integrations, frontend/modules, a root Node workspace, a new test hierarchy, or a new repository catalog. Those structures do not yet solve a proven problem that cannot be handled by the current paths.

P1-002 deliverable	Proposal state
target layout and folder creation rules	USER-APPROVED; RP1~RP6 A, current paths retained
current-to-target move map	USER-APPROVED; RM1 A, no MOVE_NOW row
reference module	USER-APPROVED; RF1 A selects mapping-only oms.commercial-order
staged wave plan	USER-APPROVED; corrected SW1 preserves Roadmap dependencies and owning-Task retirement
actual source move	NOT_RUN and not authorized
exact empty-scaffold cleanup	DONE; eight approved README/.gitkeep files removed after caller-zero review
final target approval	USER-APPROVED; recorded in Reset Revision 13 and canonical owners

2. Decision principles

1. Preserve a working path unless moving it has a named consumer, owner and measurable benefit.
2. Physical location does not create business, process, tenant or profile authority.
3. Keep current api/index.php route-manifest glob depths, page registry paths, direct HTTP paths, build inputs/outputs and consumer-bound document paths fixed until a same-change consumer migration is approved.
4. Add no new customer/profile source tree. CTC and MK variation remains profile, module, capability, policy, terminology, template and adapter configuration over one source line.
5. A module eventually needs one approved manifest and public contract, but P1-002 does not invent their schema or scaffold empty files. P5-002 owns that standard after P5-001, P4-003 and the approved P6-002 process contract.
6. Classify authored, generated, vendor, compatibility and Runtime state by evidence, not by directory name.
7. Move one bounded owner at a time. Retain a compatibility path only when a current caller requires it, and remove it only after caller, loader and deployment zero are proven.

3. Proposed target tree

All paths below already exist. The proposal changes responsibility rules, not the current filesystem.

/
├── router.php, .htaccess, index.php, login.php, admin-console.php, cron.php
├── api/                         # API dispatcher entry
├── config/                      # bootstrap, paths, page/module registry
├── app/
│   ├── platform/                # cross-module Platform Core/process infrastructure
│   ├── systems/{YMS,TMS,WMS,OMS,BMS}/
│   │                             # business-module authority and route contracts
│   ├── shared/                  # cross-module technical mechanisms
│   ├── addons/                  # optional in-process add-ons/adapters
│   ├── controllers/             # current compatibility endpoints only
│   └── utils/                   # current mixed compatibility/vendor quarantine
├── frontend/{pages,partials,scss}/
│                                 # server UI, global shell, authored styles
├── public/                      # direct HTTP entries and deployable assets
├── integrations/               # external client source
├── voice-gateway/               # separate package and Runtime
├── scripts/                    # scoped tools; migration-path owner pending
├── tests/                      # current PHP runner-compatible suites
├── database/                   # migration/seed/reference; migration-path owner pending
├── docs/                       # P1-001 document hierarchy and Runtime inputs
├── .agents/                    # agent rules, skills and retained reference
├── reference/                  # bounded historical source
├── storage/, media/            # protected Runtime state boundaries
└── .codex/, .github/           # local/collaboration tooling metadata

The caller-zero app/bootstrap/, app/routes and app/portals/{client,driver,scale} README/.gitkeep scaffolds were removed under the approved RP6 decision. They are not target paths.

3.1 Existing-path responsibility contract

Path	Purpose and owner	Allowed files	Public/private boundary and consumers	Test/module/process relation	Migration/removal rule
root Runtime entries	HTTP, session, shell and scheduled invocation	current named entry files only	externally or scheduler invoked; exact deployed document root remains UNKNOWN	routes into page/API/job owners	keep exact paths until host/deploy and all callers migrate atomically
api/	one API v2 dispatcher	dispatcher/runtime entry only	public authenticated API surface	loads module route contracts	manifest depth change requires same-change loader and route verification
config/	bootstrap, paths, environment and registries	configuration and declarative page/module maps	private source consumed by page/API/job Runtime	maps pages and module access; owns no business transition	config and consumer change in one rollback unit
app/platform/	Platform Core	tenant, auth, capability, menu, audit, process infrastructure and cross-module platform mechanisms	private implementation behind page/API/job entries	applies to every profile; process behavior remains in approved process owners; no yard/order/inventory decision	keep; move business behavior to its proven module only in a bounded Task
app/systems/<SYSTEM>/<module>/	module business authority	module query/write handlers, module helpers and api_routes.php	private implementation plus public route declaration	current YMS/TMS/WMS/OMS/BMS mapping remains; profile code may not copy it	keep current depth; future manifest/public-contract standard follows P6-002 process authority and P5-002
app/shared/	cross-module technical mechanisms	explicit cross-module technical contracts; adoption count is evidence, not authority	private implementation; does not acquire record authority	no module-specific transition or mutation decision	keep and narrow; move business helpers only after owner/caller proof
app/addons/	optional in-process add-on or adapter behavior	optional integration/report/AI/notification code	private adapter logic behind explicit API/job/public transport	core mutation delegates to the owning module	keep; do not create a second app/integrations tree without an approved need
app/controllers/	existing compatibility entrypoints	current compatibility files and an approved temporary path shim only	caller-specific boundary	no permanent forwarding wrapper or new business logic; a shim requires owner and expiry	freeze normal additions; retire shim/file after parity plus caller-, loader- and deploy-zero
app/utils/	current mixed first-party utility and vendor compatibility area	existing files only until provenance mapping; emergency maintenance in place	private, broadly included and license-sensitive	does not become a business owner	no bulk move; migrate one proven owner/package with include parity and rollback
frontend/pages/	registered server-rendered pages	page adapters and page-local presentation	routed UI source; registry and direct callers both matter	UI invokes module public contracts and owns no business authority	keep until P7 page/API/state/lifecycle boundary is proven
frontend/partials/	global shell and dependency composition	global layout/dependency fragments	broad Runtime consumer	cross-page presentation only	keep; decomposition is P7 work with sampled page verification
frontend/scss/ and declared build inputs	authored style source	current manifest-declared inputs	private source compiled to exact public outputs	shared presentation	change with build manifest, output and verifier
public/assets/js/modules/	authored browser modules under current web root	first-party browser source	directly served and tag/helper loaded	page-local or shared client behavior	do not classify as generated; move only with tag/build/deploy caller-zero
public/assets/vendor/	third-party, internal compatibility and declared generated KJ files	existing packages and exact declared outputs	directly served	dependency or compatibility surface	new copy requires package/version/license/maintainer; move by exact consumer set
other public/ entries	OAuth, webhook, callback, legal and machine transport	HTTP transport and static public artifacts	public entry; secrets/state/business authority forbidden	delegates to module/platform/add-on owner	exact URL, auth, retry, reconciliation and deployed reachability before move
integrations/gmail-addon/	external Google Apps Script client	external client source	deployed outside the PHP Runtime	calls the current public Gmail add-on endpoint	source and external deployed revision verified separately
voice-gateway/	standalone TypeScript voice Runtime	its own source, manifest, lock, tests and service examples	separate service boundary	adapter/provider behavior; not frontend source	retain separate package; service/deploy parity required before restructure
scoped build directories under scripts/	current frontend build registry and build units	declared manifests, inputs, outputs and verifiers	build-time only	exact build member	keep scoped packages; no root workspace until a real cross-package operation needs it
other scripts/	operator tooling	existing build, migration, import, operation, repair and analysis tools	effect varies by script	must name owner, environment, tenant, read/write/provider effect, dry-run and rollback	no broad re-foldering; classify before any move
tests/unit, tests/integration, tests/integration-db	current PHP test suites	files discoverable by the current runner	test-only	exact tested source/contract must be stated	retain flat discovery until runner change and same-change discovery proof
tests/*.test.mjs	current Node contract checks	existing direct tests	test-only	no canonical aggregate runner currently proven	keep exact paths until a scoped runner owner is approved
scripts/migrations/	large current executable migration/rollback collection	existing files only pending owner decision	DB effect; execution separately approved	active source/path consumers exist, but operator/deploy/applied lineage is not established	keep exact paths; physical coexistence does not approve a second migration lineage
database/	current DB support tree whose README claims migration/seed/reference ownership	existing migration, seed and reference files	not live DB truth	one uncatalogued migration conflicts with the larger scripts/migrations/ collection	keep exact paths; physical coexistence does not approve a second migration lineage; resolve owner only after operator/deploy/live-lineage evidence and user decision
docs/	canonical documents, research/evidence and selected Runtime inputs	classes and paths approved through P1-001	human/AI plus in-app manual and literal metadata consumers	module/process/manual relations follow approved hierarchy	consumer-bound paths move only in same-change consumer migration
.agents/	current agent rules and skills	engineering control sources and bounded historical reference	agent consumer, not product Runtime	may route to technical/document owners	no copied Product/Task status authority
reference/	bounded historical CTC/MK/YP input	historical source only	scoped search found no active Runtime consumer; all other external use remains UNKNOWN	research input, never current authority	remove only after absorption, retained-value review and caller-zero
storage/, media/	protected Runtime state boundaries	Runtime state only; current tracked evidence is a known conflict	private/non-executable	record owner and backup semantics remain UNKNOWN	mount, permission, backup and consumer proof before move
/temp, output/, local tmp/	ignored compatibility/output state	no new authority	local/deploy state is UNKNOWN	no module ownership	do not promote to a new top-level standard; resolve config/host consumer first
.codex/, .github/	local agent and collaboration metadata	current tooling metadata	non-product	no business/process authority	no GitHub Actions workflow; keep separate from Runtime

4. New-folder admission rule

Use an existing approved owner whenever it can hold the file without violating its responsibility. A new folder is allowed only after one review record answers all of the following:

1. exact problem and why an existing owner cannot hold it;
2. single owner and approved purpose;
3. allowed and forbidden file classes;
4. public/private boundary;
5. Runtime, build, deployment, operator and external-path consumers;
6. test location and current discovery command;
7. module, process, tenant/profile and adapter relationship;
8. source-to-target map and temporary compatibility path, if any;
9. rollback unit;
10. caller-zero, loader-zero and deployment-zero removal condition.

A new top-level or module folder also requires explicit user approval. Empty scaffolding, speculative placeholders and customer/profile-specific source folders are not allowed.

5. Approved current-to-target move map — USER-APPROVED

This section was revalidated after target approval and approved as RM1 A. It authorizes no source move in P1-002.

KEEP_AND_NARROW is the proposed target decision if approved: it avoids path churn while making future additions predictable.

Current surface	Proposed target action	Compatibility and proof gate	Rollback/removal
root entries, api/, config/	KEEP_AND_NARROW	actual document root, direct reachability, registry and loader proof before any path change	same-change revert of entry/config/consumer
app/platform/	KEEP_AND_NARROW	caller and business-authority review	move only the wrongly owned behavior; retain platform callers
app/systems/{YMS,TMS,WMS,OMS,BMS}	KEEP_AND_NARROW	module/process/tenant/caller inventory, then P5 manifest/public-contract standard	one module per rollback unit; no app/modules big-bang rename
app/shared/	KEEP_AND_NARROW	explicit cross-module technical contract and owner; adoption count is evidence only	old include removed after caller-zero
app/addons/	KEEP_AND_NARROW	owning module, provider effect, config, retry/reconciliation evidence	one add-on/adapter per rollback unit
app/controllers/	FREEZE_THEN_RETIRE	replacement behavior and direct/dynamic caller-zero	restore exact compatibility file on regression
app/utils/	FREEZE_AND_CLASSIFY	first-party/vendor allowlist, package/version/license owner and complete include map	migrate one owner/package; keep old path until caller-zero
frontend/pages, frontend/partials	KEEP_UNTIL_P7	page registry/direct callers, API/state/lifecycle and browser evidence	page-local rollback; no broad frontend move
public/ and public/assets/	KEEP_AND_CLASSIFY	exact authored/generated/vendor/public-entry allowlists plus tags/helpers/build/deploy proof	exact URL/output preserved until consumer-zero
integrations/, voice-gateway/	KEEP_SEPARATE	external deployed revision or service parity evidence	package/client-specific rollback
scripts/	KEEP_AND_CLASSIFY	per-script effect, owner, dry-run and rollback; current build manifest remains authoritative for its two units	script-specific move only
PHP test suites and tests/*.test.mjs	KEEP_CURRENT_DISCOVERY	runner supports target path and proves unchanged discovery count	revert runner and test move together
scripts/migrations/, database/migrations/	KEEP_PENDING_OWNER_DECISION	both paths exist and database/README.md claims migration ownership; operator/deploy caller and live schema lineage are unproven	keep both exact paths; decide and migrate only in one approved rollback unit
docs/	FOLLOW_P1-001	approved hierarchy plus human/AI/link/Runtime consumer proof	same-change document/consumer revert
reference/	KEEP_PENDING_ABSORPTION	retained value and no active consumer	Git preserves deleted history after approved cleanup
storage/, media/, temp/output paths	KEEP_PENDING_HOST_PROOF	mount, ownership, backup, permissions and deploy consumer	host and source rollback planned separately

No MOVE_NOW row exists.

5.1 Move-map decision

ID	Option A — recommended	Option B	Impact
RM1	approve all Section 5 actions as the move rule; execute no source move in P1-002	revise one or more Section 5 actions before approval	A preserves current consumers and defers each physical move to its proven owner; B requires the exact row and replacement action

The approved decision is:

P1-002 RM1 A

6. Approved reference mapping module — USER-APPROVED

6.1 Candidate: oms.commercial-order

oms.commercial-order is the approved mapping reference with read, write, public-route and legacy transport seams. It is not an approved conversion target.

Required seam	Current evidence	Candidate disposition
module identity	config/modules.php maps list and print pages to oms.commercial-order	preserve module key
page entry	config/page_routes.php maps the editor and print page under frontend/pages/system/OMS/commercial-order/	preserve current URLs and exact paths
public contract	Runtime route manifest, page caller and process registry include options, next-number and CRUD; current API contract owners omit next-number	record active route/caller evidence and PUBLIC-CONTRACT DRIFT; correction waits for approved owner integration
query/read model	query handler/helper own options, number, list and detail reads	map responsibilities before splitting the 637-line helper
command/use case	post handler/helper own CREATE, UPDATE and DELETE	map command and transaction boundaries before splitting the 655-line helper
transport adapter	API v2 routes and legacy query/post shells use shared endpoint helpers	preserve both until API/page/direct caller parity and legacy caller-zero
provider/hardware adapter	no provider or hardware effect was found in the current module files; returned sync-task lists are empty	NOT_APPLICABLE to the current candidate contract; recheck during implementation
process/manual	MK commercial-order workflow and operator manual are linked from current docs/registry	preserve consumer-bound paths; field freshness remains unproven
test evidence	one unit check inspects strict-principal route metadata; current docs contain historical browser evidence	CRUD, transaction, rollback, tenant and uncertain-response read-back tests remain gaps
manifest	module identity is spread across config, route contract, guard and docs	no new manifest in P1-002; P5-002 owns the schema
ownership/dependency boundary	inbound reads commercial-order tables directly; outbound uses an inbound helper; the print page directly includes the commercial-order query helper; the editor is 1,828 lines	actual conversion waits for complete callers, dependency rules and bounded use-case split

Why this candidate:

• it already keeps read/write handlers and helpers in one module folder;
• it has an explicit module key, editor/print pages, API v2 CRUD contract and process/manual trace;
• it exercises query, command, transaction, legacy transport and public contract seams without a provider or hardware dependency;
• selection requires no source move, DB write or new abstraction.

It is not yet a complete reference implementation. If activated, P5-005 is the planned future conversion owner and currently depends on P5-002 through P5-004 plus P4-006. Its final module selection remains a P5-005/user decision.

oms.trade-summary was not selected because a read-only module cannot exercise the command/transaction rule, and its helper is directly included by another module. yms.dock-scheduling was not selected because its current handler directly depends on a TMS helper. Both remain useful later read-only boundary cases.

6.2 Reference decision

ID	Option A — recommended	Option B	Impact
RF1	select oms.commercial-order as the future reference mapping module only	defer selection or name a replacement module and required seams	A covers UI, API, query, transactional write, DB, print, recovery and cross-module coupling without authorizing code change

The approved decision is:

P1-002 RF1 A

7. Approved staged-wave plan — USER-APPROVED

Wave	Scope	Entry gate	Exit evidence	P1-002 execution
W0 — P1-002 decision baseline	repository responsibility target, move map and mapping reference	P1-001 hierarchy and P1-002 decisions	RP1~RP6, RM1, RF1 and SW1 recorded	decision set recorded locally; Roadmap status unchanged
W1 — parallel read-only inventories	mixed-surface evidence, P5-001 and P7-001; P8-001 joins when its own dependencies are met	W0 plus each exact Roadmap Task activation	owner/caller/build/deploy/host unknown maps	only already-authorized P1 mapping performed
W2 — authority prerequisites	process baseline/contract and tenant/profile/query-write boundaries	P2/P4/P6 Roadmap dependencies	P6-001/P6-002 and P4-003/P4-004 approved inputs	not authorized in P1-002
W3 — repository standards	P5-002 through P5-004; P7-002/P7-003 and eligible P8 work remain independently startable under Roadmap	P5-001 plus W2 inputs and P7-001 where required	manifest/public contract, handler/repository/transaction and adapter standards accepted	not authorized in P1-002
W4 — reference conversion	P5-005 on one revalidated module; P7-004 follows only when its own dependencies are met	P5-005 activation, including P4-006 and W3	focused normal/negative/retry/recovery, contract, field and rollback evidence	not authorized in P1-002
W5 — bounded conversion waves	P5-006 and eligible P7 migration, with same-change tests/manuals/docs and owner-specific retirement	W4 plus each exact Roadmap Task activation	module/page/API/state/browser/manual/runner parity and caller/consumer-zero by owner	not authorized in P1-002
W6 — final residual audit	read-only review of unresolved compatibility, caller, loader, consumer, deploy and rollback gaps	owning W4/W5 Tasks report their own retirement evidence	closed or explicitly retained residual register; no new deletion owner	not authorized in P1-002

Wave numbers are migration ordering labels, not new Roadmap Tasks. P7/P8 work does not wait for W4 when its Roadmap dependencies are already met. Every physical retirement stays inside the owning Task's bounded rollback unit; W6 does not perform a second cleanup.

7.1 Staged-wave decision

ID	Option A — recommended	Option B	Impact
SW1	approve the dependency-aligned W0–W6 plan	revise an exact wave, dependency and replacement order	A preserves Roadmap activation and avoids treating wave labels as implementation authorization

The approved decision is:

P1-002 SW1 A

8. User decisions — target approved

2026-07-30 decision: P1-002 RP1 to RP6 all A.

ID	Option A — recommended	Option B	Impact
RP1	retain current top-level tree and approve the responsibility overlay	design a new physical top-level tree now	A avoids loader/deploy churn; B requires more current host and caller evidence
RP2	keep app/systems and app/addons; define contracts before moving	create app/modules/app/integrations first	A follows gradual extraction; B creates compatibility work before product value
RP3	freeze and classify app/utils/public; migrate one owner at a time	bulk split by current folder name	A preserves provenance and callers; B risks license, include and public-path regressions
RP4	keep current script/test discovery and add effect/owner rules	broad folder reorganization now	A preserves execution; B can silently stop test/script consumers
RP5	keep both migration paths pending operator/deploy/live-lineage evidence and decide later	designate one migration owner now	A exposes the current owner conflict; B guesses before consumer proof
RP6	delete caller-zero empty app/bootstrap, app/routes, app/portals/{client,driver,scale} scaffolds	retain them with an explicit owner/activation condition	A removes speculative duplicate paths; B requires a proven near-term consumer
The approved decision is recorded as:

P1-002 RP1 to RP6 all A

Sections 6 and 7 are approved as RF1 A and corrected SW1 A.

9. Mac Local RO environment evidence

The activated Local RO lane was inspected without starting, stopping or reconfiguring a service:

• the checkout resolves to /Users/kylejang/workspace/ctc;
• an already-running performance-harness Apache/PHP-FPM sidecar listens only on 127.0.0.1:18081;
• its external config at /Users/kylejang/.local/state/codex-harness/ctc/perf-wp-002-20260728/persistent-fpm-httpd.conf sets this checkout itself as DocumentRoot;
• that sidecar uses AllowOverride None and its own rewrite rule, so it is not proof that a deployed host consumes repository .htaccess;
• because it serves the worktree directly, it has no separate source-copy or exclusion step;
• the repository contains voice-gateway service descriptors that name /var/www/html, and docs/PRODUCTION_ENVIRONMENT.md also describes that path, but those source files do not prove a currently active Hub or Production deployment;
• no tracked general PHP application deploy/copy script or authoritative Mac deploy manifest was found.

Therefore the Mac Local web-root question is closed for the observed harness sidecar only. Hub/Production document root, copy/exclusion, active service SHA and mounts remain outside Mac evidence and must not be inferred from it.

10. Verification and residual unknowns

Migration-path read-only audit found 237 tracked files under scripts/migrations/ with current source/test/document path consumers. database/migrations/ has one SQL file plus .gitkeep, and no caller was found, but its applied state is UNKNOWN. No repository migration runner, applied-file ledger or current operator/deploy lineage was found. RP5 therefore preserves both physical paths without approving two migration lineages.

Check	Result	Meaning
origin/qa@cd26f23f4 and local Reset Revision 27	PASS / LOCAL	remote source plus uncommitted user-decision basis; no remote completion claim
Runtime/tree inventory through origin/qa@cd26f23f4	PASS	6614c9fd9..cd26f23f4 adds 13 root Node tests and changes bounded Runtime/UI/test files without repository-owner drift; audited source/filesystem proposal basis only, not deployed Runtime proof
Mac Local web server/docroot/copy inspection	PASS / PARTIAL	observed harness sidecar serves the checkout directly; it is not Hub/Production proof
node scripts/frontend-build/verify-manifest.mjs	exit 0 / ISOLATED_COMPAT	current two build units only; three blocking host/root-parity gaps remain
unresolved merge-marker and relative Markdown link checks	PASS	changed documentation surface only
actual source folder move	NOT_RUN	explicitly out of scope
Runtime/browser/DB/provider/service/Production	NOT_RUN	no behavior or external effect was authorized
Hub/Production document root/deploy/service/mount proof	BLOCKED	not provable from the activated Mac Local RO environment
reference module Runtime acceptance	NOT_RUN	candidate selection is not implementation or UAT

Residual unknowns remain:

• actual Apache/PHP document root and deploy copy/exclusion behavior;
• active cron/service identity and deployed SHA parity;
• complete dynamic include, public asset and external operator caller maps;
• exact app/utils and public vendor/version/license/update ownership;
• storage/media/temp/output mount, permissions, backup and retention;
• oms.commercial-order current DB/browser behavior, direct print parity, cross-module dependency rules and safe helper/UI decomposition.

These unknowns block physical moves, not review of the responsibility overlay.

Source: docs/research/platform-foundation/2026-07-30/proposed-repository-layout-and-migration-plan.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.