CTC Logistics Workspace Documentation Authority¶
- Status:
SOLE DOCUMENT AUTHORITY MAP - File exploration: the file index
- Task execution: AGENTS.md → Agent Workflow
This document decides the role, canonical source, allowed location, generation, and removal criteria of a document. The code placement and the shared generation decision are
SYSTEM_STRUCTURE_STANDARD, and the work responsibility
MODULE_REGISTRY The file index is responsible for exploration only and does not approve a structure.
The product root is the current new-system/, and ./ after the separation, and Legacy and reference are an external basis.
The distinction between a path and a URL follows the product root and extraction boundary.
1. Read For The Question¶
| Question | The canonical source to read and modify |
|---|---|
| What is the purpose and scope of the product | PRODUCT |
| What is built and what behaviour it guarantees | the 9 specification guide → the area, Process, and module detail of that specification |
| What is the criterion of a screen and the shared structure | DESIGN, SYSTEM_STRUCTURE_STANDARD, MODULE_REGISTRY |
| How is it developed and checked | DEVELOPMENT, the test guide |
| What is the current request, the progress, and what remains | the Task guide → the relevant Task and the current checkout and Git history |
| What is the phase order and the exit condition | ROADMAP |
| Why was it decided that way | the decision record → the relevant ADR |
| What was actually verified | PRODUCT_REALITY, the execution evidence, and the relevant original result |
| How is it operated, recovered, and used | Runbook, the Wiki |
| Where a file is | the file index |
Expand only into the detail needed from the canonical source of that question. A list registration is not evidence of a review, an approval, a freshness, or an acceptance, and the progress state of another checkout is not judged by a remote Task copy alone.
2. Lifecycle And Maintenance¶
| Kind | The update and preservation criteria |
|---|---|
| Durable | a product, design, work, or operational contract. The existing original is modified when the behaviour, ownership, or interface changes |
| Project-lived | a ROADMAP, Task, or phase plan. A long-term decision is reflected in the canonical source, and a duplicated plan or handover copy is deleted after its unique content and consumers are transferred |
| Evidence | an original with a date, revision, environment, execution result, and a limit. It is preserved when an acceptance, recovery, or migration consumer needs it; it is not deleted by a Task end or a system retirement alone |
| Compatibility or control input | a compatibility notice or a machine input that still has a real reader. The consumer, the replacement location, and the removal condition are recorded in the existing owning document, and it is deleted when the switch is complete |
| Generated | a derived result made by an existing original and a generator. It is not edited directly or used as a second canonical source |
The purpose, the reader, the update responsibility, and the cleanup condition of a temporary material are recorded only as much as needed in the existing header or the owning Task.
The same field is not copied into a separate registry, sidecar, or progress ledger.
../catalog/product-reality.json owns the capability state and the basis, and PRODUCT_REALITY.md owns the admission and the boundary.
The two are not a live tenant setting, and a document cleanup does not promote an evidence or an exposure.
3. Existing Directory Map¶
The table below is the allowed document classification. An arbitrary document cannot be added just because a folder exists. A new document must satisfy the classification, the real owner, the current request, and an independent reference purpose. A document classification or a top-level folder that is not in the table is not created before a structure change approval.
| Purpose | The allowed location | The content and the boundary to write |
|---|---|---|
| Top-level canonical source | README.md, PRODUCT.md, DESIGN.md, DEVELOPMENT.md, ROADMAP.md, PRODUCT_REALITY.md |
a document map, a product, a design, a development method, a phase, and a capability judgement. A new overall plan, progress, or policy file is not made alongside them |
| System specification | specifications/ |
the shared body and the area sections of the existing 9 SRS, SAD, SDD, DATA, INTERFACES, BEHAVIOR, SCREENS, TESTS, and RTM volumes |
| The background of a requirement | requirements/ |
the user context, the reason for the change, and the specification guide. The current requirement body is modified in that specification |
| Design | architecture/ |
a system, module, dependency, UI, quality, and identity contract. A new standard that answers the same question as an existing standard is not created |
| Area detail | processes/ |
the requirement and the process that the area section of the specification links. It is not a new progress ledger or a per-area copy of the 9 volumes |
| Screen detail | pages/ |
the contract, acceptance material, and an approved comparison or prototype per the real screen owner. A new plan or review file is not made on every modification |
| Implementation detail | ../packages/ |
a README next to the code owner, a public contract, and a detailed design that is referenced independently. An explanation file is not made for every symbol |
| The reason for a decision | decisions/ |
the alternatives, the basis, the impact, and the replacement relationship of a relevant ADR. A routine work result and a verification summary are a Task |
| Source and terms | knowledge/ |
the existing standard for terms, source tracing, and Task handover. It is not a per-AI context, memory, or operational rule copy |
| Work | tasks/ |
the request, scope, plan, result, verification, and handover of a stable Task ID. The upper and lower execution units and the evidence attachment follow the Task guide |
| Phase material | project/ |
an existing phase plan, a migration history, and a parity input. The real consumers of phase1/, phase2/, and parity/ are preserved; a new Task state table is not made |
| Source investigation | reconstruction/ |
an independent basis that compared a specific Legacy or reference source and revision. A repeated summary is integrated into the relevant specification or Task |
| Execution evidence | operations/ |
the result, the limit, and the original attachment of a specific runtime, migration, or rollback execution. A pre-execution plan and a current operational procedure are a Task and a runbook respectively |
| Security evidence | security/ |
a control verification with a date and a scope. It is not expanded into a separate security policy or a whole security acceptance |
| Operational procedure | runbooks/ |
a real target, authority, execution, read-back, and rollback procedure. A past execution result is linked as evidence |
| User guidance | the existing README.md of wiki/ |
only the manual canonical source, the exploration, and the verification contract. The operational body is T_WIKI_PAGE, and an asset is WIKI_ASSET of T_FILE and the file repository |
| Template | templates/ |
an existing template that is actually consumed. A document is not increased to fill a new template after making it |
| Structured relationship | ../catalog/ |
a stable ID, owner, relationship, source, and exploration index of the existing schema. It is not a copy of a descriptive body, a code symbol, or a work state |
| Generated result | ../.generated/ |
a derived result and the necessary generation evidence. An already approved runtime generated file follows the generated artifact boundary of the code structure standard |
Do not create parallel data/ or modules/ documentation trees.
The empty interfaces/ placeholder is retired. A public contract is in the real owning module and catalog, and
only an approved cross-runtime or external contract is placed in the root contracts/**.
The read-only presentation generated from the Git development specification, and the DB operational manual, the Wiki contractare separated according to it.
3.1 Document Creation And Naming¶
Modifying an existing original is the default. The reason and the location for increasing a document are judged as follows.
| Situation | The handling |
|---|---|
| describing the same requirement, rule, decision, or progress | modify the existing section of the specification, ADR, or Task. No new file |
| the detail of an existing specification has to be modified and referenced independently | only one kind of detail is separated under the same work owner and linked from the upper specification. The duplication in the existing body is removed |
| a work that has a separate responsibility, acceptance, and recovery boundary | the execution unit is separated according to the existing Task guide. It is not separated just because a conversation or an AI session is new |
| an original input or result that is needed for a reproduction, an audit, or a recovery | it is preserved as an attachment that is referenced from the owning Task and the existing evidence location. It is not deleted only because of a prompt, patch, or checksum extension |
| a one-off thought, a search, or a work in progress note | the current conversation, an existing Task, or an unmanaged temporary location. A new report, handover, or context copy is not committed |
| it does not fit the classification above | it is first solved in the existing owner. If that is impossible, the needed new classification, responsibility, consumer, and replacement target are presented, and it is created after a structure change approval |
The existing file name, ID, and anchor are kept first. A new detail document follows the naming convention of the same owner, and
an ADR uses NNNN-<topic>.md, an execution Task uses the existing NS... ID contract, and execution evidence uses the existing date and Task naming contract.
v2, final, new, cleanup, review, and handoff are not appended to multiply the same original.
When it is a real separate version contract or an independent original evidence, the reason and the consumer are stated in the existing owner.
A per-folder README is used only when it is actually needed for the exploration, and empty READMEs, tables of contents, and templates are not created in bulk.
The generation decision is written in the existing work plan or handover. A separate generation approval document or a file list registry is not created.
4. Consolidation And Source Precedence¶
The order is modify the existing canonical source → compare the unique content and consumers → switch the references → remove the duplication. The editing original of the same rule, command, or state is kept as one, but a specification, a decision reason, and execution evidence are not merged. A document is not deleted only by its size, age, or a search result.
An approved Product, Process, or design is the intended behaviour, the current source and execution evidence are the observed implementation, and the relevant Task describes the current work. A conflict clarifies both sources and the decision responsibility. It is not judged by a generated summary, and an initial draft does not overwrite a later DESIGN decision.
A long-term rule is recorded in the relevant specification, the reason for the choice, the impact, and the replacement relationship in the existing relevant ADR, and the work result in a Task or a DIRECT handover. When a path is changed, the direct links, the anchors, the catalog ID and relationship, and the scripts, tests, runtime, and Wiki reader are checked together. A past revision, hash, verification date, and acceptance level are preserved. A historical original can be referenced by an immutable revision.
A popup appearance is owned by DESIGN, the shared interaction by the UI Foundation, and a field and a command by the relevant Page or Process. The page evidence and history follows Quality Gates. A document cleanup is not a basis to relax a required evidence, to change a Task state, or to overwrite another session's change.
4.1 Retired Systems And Deletion¶
A retired operational system is not kept in the current tree permanently. Once the transfer of the unique content and the switch of the real consumers are finished,
the instruction, template, progress ledger, and duplicated implementation of that system are deleted in the same cleanup scope. A DEPRECATED mark or a move to another folder alone does not complete it.
- A retired EXECUTION ledger, a Task manifest, preflight, or Context Gate, and a parallel intent, spec, plan, or proof system are not used or restored as the generation and progress basis of new work.
- A compatibility file that still has a current link, parser, or external reader is a switch remainder, not a completed removal. The real consumer, the replacement canonical source, and the removal condition are left in the existing owner, and a new dependency is not added.
- A historical decision, an original execution evidence, and an approved recovery material are different from a retired execution system. A needed original is preserved or linked to an immutable Git revision, and then only the unnecessary copy is deleted. An attachment that an audit and a recovery need is not deleted only because it is in the Git history.
- An old
Live status, command, and next work written in an existing document is organised by distinguishing the current instruction from a historical quotation. A past test result or a user approval itself is not rewritten as a current fact. - When a consumer that blocks the deletion, or a change by another author, exists, only that file is preserved and the reason is recorded. This is not used as a reason to keep a whole retired system indefinitely.
The shared completion condition of a document retirement and a code removal follows the code structure standard §12. A deletion list, a retirement registry, and a separate archive tree are not newly created.
5. Progressive Startup¶
the root and scoped AGENTS and Agent Workflow → the relevant canonical source of §1 → the needed detail are read in order. Before a new path is made, the document classification of §3 and the generation contract of the code structure standard are compared. A Task-backed work uses the relevant Task, and a DIRECT work uses the handover of the scoped AGENTS. The whole document or a past packet is not read in advance, and a parallel intent, spec, plan, or proof tree is not created. The needed input of the selected primary skill is kept.
6. Verification Owners¶
| Existing check | The confirmed scope |
|---|---|
../scripts/docs/validate.mjs |
the document canonical source, links, and the execution guide |
../scripts/tests/quality/docs-authority.test.mjs, documentation-layout.test.mjs |
the canonical source, structure, and handover contract |
../scripts/catalog/validate.mjs |
catalog schema·identity |
../scripts/quality/product-reality.mjs |
the capability and governance relationship |
../../.agents/harness/validate.mjs |
the routing and skill contract |
The execution command and the check selection are owned by the test guide
The new file, move, rename, and deletion in the final diff are compared with the classification of §3. An existing check PASS or a file index registration
does not replace the approval of a new structure. File creation is not technically blocked automatically by the rules of this document alone.
A new validator, hook, CI, or registry is not added because a structure is being cleaned up.
A document check proves only the consistency of a structure, a link, and a command, and does not replace a browser, DB, or work acceptance.
When the environment for a required execution is absent, or it was not run, it is distinguished as BLOCKED or NOT_RUN.
7. Traditional Development Documentation¶
7.1 Definition And Owners¶
The development specification is 9 volumes of a requirement, an architecture, a detailed design, data, an interface, a state and sequence, a screen, a test, and an RTM.
Each volume of specifications/ owns the shared system body and the area sections, and links to the existing detail originals.
The per-document definition, the reading order, and the authoring structure are in the 9 specification guide
DEVELOPMENT.md is a development work guide and is not the whole specification, a Task record, or a user manual.
7.2 Client-Specific Source Basis¶
| Target | The source basis |
|---|---|
| Client ID 1 | the Legacy runtime, work, sequence, and schema material of the current parent checkout |
| Client ID 2 | the reference/mkmetal/ material of the parent checkout, and the product internal code, contract, and test |
Each specification distinguishes the applied Client, the real path, the revision and material time, the verification scope, and an approved requirement, a reconstruction, the current implementation, a target, an unconfirmed item, and a difference. The requirement of one Client is not replaced by the source of another Client, and a conflict between the reference and the implementation is linked to a decision responsibility. A shared contract is defined once, and only the per-Client application and difference are attached. A per-Client code or module fork is not created. Client ID 1 is also a technical specification target. A new manual and Wiki writing targets only Client ID 2, and the existing C1 content, exposure, and the authoring and publishing hold are preserved.
7.3 Specification First, Derived Documents Second¶
The authoring order is the structure, the shared body, and the area contents of the 9 whole-system specifications → the area section detail → the needed development guide, runbook, and manual. Booking is one area, and a feature implementation and the real acceptance are not a precondition for another document authoring. A document structure cleanup, a work meaning analysis, an implementation, and the real acceptance are separate scopes. A document request is not expanded into a CRUD, a DB fixture, or a feature fix. The completion of an area is judged by whether the change impact and the execution evidence are traceable from the requirement, not by the number of documents. The basis and the owner of an open item and the existing result are kept, and a derived manual distinguishes a verified behaviour from an unverified draft. The DB save, the same UUID read-back, the exposure, and the procedure execution of an operational manual are each confirmed.
7.4 Corpus And Document Units¶
The 9 whole-system specifications → the area sections of each specification → the needed area detail documents is the base structure, and a per-area collection is a supplementary exploration.
The unit of one document is one kind of specification × a cohesive target or responsibility. Only the detail that is modified and referenced independently is separated under the existing owner.
A shared SAD, data, and authority is not duplicated per area, and an empty file is not made for a short section or an unwritten area.
The original and ID of the 8 Booking details and the Receipt detail are preserved, and the 9 volumes or all the area bodies are not merged into one page.
Each document is discovered by its specification metadata, and the base order is set by the volume of the 9 system volumes. A detail original has no volume.
An existing integrated URL or section anchor is linked to that individual document, and the display and navigation follow the Wiki structure.
8. Knowledge Maintenance¶
8.1 Claims, Identity And Projections¶
The meaning of a work and a design is recorded in a descriptive document, and a stable ID, owner, relationship, and source are recorded in the catalog.
A code symbol is not copied into a descriptive document, and a required value, access, or recovery rule is not newly defined in the Wiki.
When there is an uncertainty, CONFIRMED, INFERRED, UNKNOWN, CONFLICT, STALE, and SUPERSEDED are distinguished.
A catalog ID is kept even after a file is moved, and the source, checksum, verification, and freshness follow Source Registry.
An AST graph, a search index, a trace, and a context pack are derived material of ../.generated/. When it is used as a basis, the source revision and the tool version are recorded, and
it is refreshed when the relevant original changes, but it is not treated as an editing original or an approval of a specification. The preservation criteria follow §2.
8.2 Change-Scoped Updates¶
The exact Task declares which documentation, catalog, runtime evidence or Wiki changes
are required for that slice. For DIRECT maintenance, record the same bounded impact and proof in
the handoff instead of creating a Task. There is no universal requirement to create a page document,
screenshot manifest, Wiki article and changelog for every page edit. Retain durable evidence when
acceptance, release, recovery, compliance or a post-Task consumer requires it.
| Change | Required update | Not required by default |
|---|---|---|
| Internal move with unchanged operator behavior | affected source check, ownership reference and handoff | Wiki, page version or change-history churn |
| Shared UI behavior change | shared contract and affected representative consumer regression | unrelated page documents or manuals |
| Field, business-rule or recovery change | Process/page contract, focused test and changed operator procedure | copied Foundation/phase prose |
| Visual change | approved design source and relevant visual evidence | unrelated data or business-contract changes |
| Documentation path move | direct readers, indexes and link/anchor checks | Product runtime acceptance claim |
Update the existing owner when a changed public contract, Process, ownership boundary, policy,
integration, recovery behavior or accepted user flow would otherwise misroute future work.
Quality Gates §10.1–10.4
owns page-script/scenario/version, screenshot and history proof; the Wiki owns the
operational DB content/assets and navigation, separately from Git-derived read-only specification consumers. A required acceptance check remains required
when execution is unavailable: report BLOCKED or NOT_RUN, not source-only acceptance.
Source:
new-system/docs/README.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.